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^ Foreword 



' For most people who learned machine language on the Apple 
II, the Commodore 64, and the Atari 8-bit machines, the pros- 
P"~] pect of progressing into the 16/32-bit territory of the Amiga — 
with its multitasking environment, windows and mouse input, 
and libraries of subroutines — can be daunting. 

Until now, there was no simple way to get started. 

But now, with COMPUTEI's Amiga Machine Language Pro- 
gramming Guide, Daniel Wolf and Douglas Leavitt, Jr. provide 
an easy path to learning Amiga machine langage program- 
ming. In this book, you'll find sample programs that cover 
nearly all of Amiga's special features, along with helpful hints 
and suggestions on programming technique and organization. 

COMPUTEI's Amiga Machine Language Programming Guide 
provides a thorough explanation of the use of Intuition, in- 
cluding Intuition windows, menus, and requesters. You'll un- 
derstand how to use button, string, and slider gadgets, and 
how to write programs that interact with the user through CLI 
and console windows. 

Structures and fields (the individual bytes, words, or long 
words within a structure) are covered in detail, and their use 
in AmigaDOS function calls is explained. Floating-point math 
is explored, along with a look at "transcendental" math func- 
tions used in trigonometry. And, sample graphics programs 
that use these high-level math functions to provide fractals 
and three-dimensional graphics are included. 

Appendices explaining 68000 instructions and addressing 
modes, macros, pseudo-ops, and assembler directives round 
out the book. 

In short, this feature-packed book is perfect for anyone in- 
terested in programming the Amiga in machine language. 

Please note: Because of the advanced nature of machine 
language programming, it would be difficult to work with an 
unexpanded Amiga and a single disk drive. For this reason, 
the material in this book was written with the assumption that 
the programmer has an Amiga computer with at least 512K 
and two disk drives. 



H 



The programs in COMPUTEI's Amiga Machine Language 
Programming Guide are available on a disk, along with 
the ASM68010 assembler. If you wish to purchase this 
disk, call toll free 1-800-346-6767 (in New York, 212-887- 
8525). Or, use the coupon found in the back of this book. 
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Introduction 



The Amiga family of microcomputers includes three members: 
the original Amiga 1000 and the newer models 500 and 2000. 
They are software compatible and share a complement of 
hardware features that make them among the most powerful 
personal computers in today's market. Amigas have especially 
versatile color graphics capabilities and a multitasking operat- 
ing system that permits operation of different programs 
simultaneously. 

The architecture of these computers integrates a Motorola 
MC68000 microprocessor and special-purpose processor chips 
for graphics, sound, and input/output. The Amigas can be ex- 
panded with a variety of memory boards, disk drives, graphics 
devices, and other peripherals. Amigas feature a built-in user 
interface consisting of mouse-based interaction with windows, 
menus, and icons. The Amiga system is well suited to a wide 
variety of productivity, business, artistic, and entertainment 
applications. Amigas are used in professional television broad- 
casting, program art production, personal word processing and 
desktop publishing, as well as in business management. 

Programming the Amiga 

With such a capable system of hardware and software, pro- 
grammers find the Amiga inviting as well. Already, several 
programming language packages are available for the Amiga, 
including C, Fortran, LISP, and several dialects of BASIC. Be- 
cause the Amiga's microprocessor is a Motorola MC68000, ex- 
isting language packages that operate on other MC68000- 
based systems have been easy to transport to the Amiga. The 
MC68000 is the same 16/32-bit processor used in the Apple 
Macintosh family and the Atari ST series. Machine language is 
just another programming language for the Amiga, similar to 
these others, except that it executes much faster and takes up 
less space than most languages. 
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Why Machine Language 

(1 With such a range of high-level languages (C and BASIC, for 
instance) available for the Amiga, some justification seems re- 
; quired for programming in machine language. 
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First, since all microprocessors (such as the 8080, Z80, 
8088, and the 6502) have their own machine languages, there 
is a community of programmers already familiar with machine 
language techniques. Some programmers, who have already 
used MC68000 machine language on other computers, will 
naturally prefer similar working methods for Amiga software 
development. 

Second, regardless of the type of microprocessor, machine 
language is the most direct means of programming the micro- 
processor. All high-level languages translate their programs 
into machine language, either through an interpreter or by 
means of a compiler. Compiled languages (C and Fortran, for 
instance) run their code through compilers, which translate 
their programs into machine language. BASIC usually has an 
interpreter that translates the BASIC program into machine 
language, instruction by instruction, as the program runs. 

Machine Language Source Code and Object Code 

Machine language is written in a kind of shorthand. The ma- 
chine language programmer arranges short-hand codes for in- 
structions, in a sequence, to accomplish a specified task. 

Translating these shorthand codes (collectively known as 
source code) into the numbers that instruct the computer 
(known as executable code) is accomplished by a program 
called an assembler. An assembler is like a compiler in that the 
code is translated only once and the result is a program that 
will run on its own, without an interpreter. The only way to 
program the microprocessor more directly is to place the nu- 
merical instructions in memory yourself. The assembler re- 
lieves programmers of the need to work with long binary 
numbers — strings of ones and zeros that are confusing and 
difficult to read. 

The assembler examines the three- or four-letter opcode 
in the source code, looks up its numeric equivalent on a table, 
and places the object code in a memory location. When a ma- 
chine language program is assembled, there's nearly an exact 
correspondence between the source code instructions and the 
object code instructions. When high-level languages are com- 
piled, a more complicated translation usually takes place, and 
it's difficult for the programmer to anticipate what the object 
code will look like. It is likewise difficult for the high-level 
language programmer to predict the size and speed of the 

viii 
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compiled program. Usually, the translation process for high- 
level languages is not a direct line-by-line replacement of code 
with numbers. A single statement in a high-level language 
might be translated into a long sequence of numerical instruc- 
tions for the microprocessor. 

One advantage of machine language is the fact that it is 
the most direct means of controlling the microprocessor. In ad- 
dition, machine language usually provides the most compact 
finished programs because of the direct translation to instruc- 
tions for the microprocessor. 

A third advantage of machine language is that the pro- 
grammer can and must make decisions about the use of inter- 
nal registers of the MC68000 and almost all other aspects of a 
program's size and speed. 

The proper use of registers powerfully affects a program's 
efficiency of operation. High-level languages leave these deci- 
sions to the compiler or interpreter. When using machine lan- 
guage, such decisions must be made expressly by the pro- 
grammer. Because some instructions run faster when using 
registers, this means the machine language programmer may 
produce faster programs by using the registers intelligently. 
This aspect of programming is called optimization. 

In summary, machine language for the Amiga offers these 
advantages: 

• Similarity to other microprocessor machine languages 

• Direct and concrete step-by-step microprocessor control 

• Absolute programmer control over the program's speed and 
size (which affect the program's overall efficiency) 

The disadvantages of machine language include: 

• Explicit control of the microprocessor requires thorough 
knowledge of the instructions and how they work. 

• Machine language provides a maximum of freedom which 
must be harnessed by a maximum of programmer 
responsibility. 

• Source program size can be a problem. A single line of 
source code may accomplish a great deal in a BASIC pro- 
gram. A single line of machine language source code is often 
a single microprocessor instruction; therefore, a machine lan- 
guage source program may require a large number of lines of 
code to accomplish even the simplest task. 
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For the programmer who wishes to have complete control 
of the machine and who is willing to accept the responsibility 
for detailed programming, machine language is the language 
of choice. 

A Note on the C Language and Amiga 

C is a language that was developed during the 1970s at Bell 
Laboratories. It became the native language of the UNIX op- 
erating system. Because C has a fairly simple structure, it is 
easily moved (or ported) to other microprocessors. The process 
involves writing a C compiler for the particular microprocessor 
(a process that takes place in either C itself or in the machine 
language for the microprocessor in question). There are C 
compilers available for most of the popular microprocessors 
and personal computers. 

Since C compilers are available on so many machines, it's 
usually possible to move a C program to a new system simply 
by compiling the existing source code on the new machine, 
using its C compiler. Moving machine language programs is 
usually more complex and may not be possible when two 
computers use different microprocessors. 

The C language has also become a very popular system 
programming language for professional programmers. Its fea- 
tures make it convenient as a high-level language, but it also 
has many low-level features surprisingly similar to machine 
language source code. These low-level features make C similar 
enough to machine language that professionals call it the sys- 
tem programmer's machine language. Such professional pro- 
grammers heavily exploit the low-level features of C and the 
result is like a machine language that can be easily ported , t 
from computer to computer. I I 

A small part of each C compiler must deal with the spe- 
cific microprocessor. Fortunately, this machine-dependent part , . 

is transparent to the programmer. The C programmer usually j | 

is insulated from the specifics of the computing hardware. It 

isn't surprising that C was also the language chosen by the , , 

Amiga software development team. | ( 

The early Amiga programmers couldn't even use Amigas 
for writing programs. They used Sun Microsystems computers , ■ 

(also equipped with MC68000 microprocessors) or IBM PC j J 

systems (with 8088 microprocessors) and sent programs over a 

cable to the Amiga's memory. — . 
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C provided a common and (as high-level languages go) 
efficient programming language for the complex Amiga hard- 
ware while it was still under development. That means that 
the history of Amiga software development has been strongly 
influenced by C. 

Much of the documentation provided for the Amiga pro- 
grammer assumes programs are written in C. Since C is close 
to machine language in efficiency, speed, and program size, 
this is not a disadvantage. Some C compilers actually include 
an assembler. In these compilers, the C language source code 
program is first translated into an equivalent machine lan- 
guage source program, and then it is assembled. 

Nearly anything that can be done using C on the Amiga 
can also be done using machine language, and vice versa. On 
the Amiga, machine language and C have a very close rela- 
tionship: C is the Amiga's native language, and machine lan- 
guage is the MC68000 microprocessor's native language. 

One important feature of machine language on the Amiga 
is that it provides access to all the C-based aspects designed 
by the Amiga's system programmers, without requiring a 
knowledge of C itself. 

In summary, a choice between C and machine language 
on the Amiga is one of personal taste and style. They are 
nearly equivalent in power. Assembly language is still more 
efficient and direct and, of course, doesn't require that the pro- 
grammer learn C (which does have some complicated and 
tricky features). Machine language is sometimes used to stream- 
line the performance of a critical section of a C program. 

Commodore has provided program developers with com- 
plete machine language development packages, but-there has 
been less documentation publicly available about Amiga ma- 
chine language programming. This book integrates some of 
the needed information into one volume to make machine lan- 
guage more accessible to Amiga programmers. 

About This Book 

The purpose of this book is to introduce Amiga machine lan- 
guage programming to a wide audience, including both new 
and experienced programmers. Examples of programming 
methods as well as complete programs are provided to show 
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how readers can construct their own applications that take ad- 
vantage of the Amiga's powerful features. The example pro- 
grams demonstrate: 

• AmigaDOS console use 

• AmigaDOS function calling 

• Intuition window open, close, user interactions 

• Intuition menu layout and interactions 

• Intuition button, string, and slider gadgets 

• Intuition window graphics 

• Intuition requesters 

• Floating-point math 

In addition to the short example programs that demon- 
strate the Amiga's features, there are four program listings that 
show how Intuition, Graphics, Math, and AmigaDOS features 
may be combined into larger programs: 

• QUADRIX.ASM demonstrates 3-D graphics. 

• LENS.ASM is a Workbench screen/window that provides a 
variable magnifying window. 

• POLYFRAC.ASM demonstrates fractal line drawings. 

• ASMINT.ASM provides an Intuition interface for machine 
language development. 

The information topics covered include the following: 

• Overview of important CLI commands 

• Organizing your working environment 

• Using an Amiga-compatible assembler 

• A first program 

• The MC68000 instructions 

• The MC68000 addressing modes 

• MC68000 techniques: 
Macros 
Subroutines 
Branches and loops 
Arithmetic 

Strings 

• Amiga programming techniques: 

Symbol definitions for ROM Kernel software include files 
Library calls and register parameter passing 
Memory and multitasking 
Startup program requirements 
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• AmigaDOS and files (open, close, read, write) 

• Intuition (windows, text, menus, gadgets, requesters, screens) 

• Graphics (rastports, pixels, colors, lines, fills) 

• Floating-point math (text conversion to floating point, hex 
dump) 

The appendices have tables of important Amiga symbols 
and data for the assembler. Complete type-in listings are also 
provided for all the Amiga symbols used in the programs. By 
using these files (or the companion disk to this book), you can 
enter, assemble, and use these programs as well as write your 
own applications. The Intuition section presents topics in a 
building-block order, developing windows and text concepts, 
following with gadgets and menus (typically associated with 
text), and then requesters (which typically use gadgets and 
text). 

For each appropriate section, there's an associated type-in 
file of useful macros and subroutines that are used as program 
building blocks throughout the succeeding parts of the book. 
These macros and subroutines were tested and designed to re- 
duce repetitive coding. This is typical of Amiga programs, 
which have many modular data tables (or structures). In many 
cases, the use of complex Amiga features in a program can be 
accomplished with just a few lines of source code consisting of 
these macros and calls to the related subroutines. Source code 
is readable and easily modified, with text structure declara- 
tions limited to the text strings themselves. 

At the end of the book is a complete listing of MC68000 
and MC68010 microprocessor instructions, assembler 
directives, and pseudo-ops. Where the assembler documenta- 
tion might be specific to the ASM68010 assembler, included on 
the companion disk available from COMPUTE! publications, a 
note is made: Those using other assemblers (Metacomco, for 
instance) can refer to these notes and use the alternative syn- 
tax appropriate to their particular assembler. A great deal of 
effort has been expended to make this assembler documenta- 
tion section compatible with both ASM68010 and the Meta- 
comco assembler. 
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About the Companion Disk 

A disk is available from COMPUTE! Books which provides 
readers with all the program listings and files presented in the 
book. It can make your use of the book's programs easier by 
eliminating almost all of the typing. 

The disk also has a machine language development sys- 
tem for the Amiga. This includes ASM68010, a fast Amiga as- 
sembler. There is also the ASMINT program, which provides 
the ASM68010 with a mouse interface. ASMINT has Intuition 
gadgets to handle most user interactions and is ideal for begin- 
ners with little CLI experience. The disk is designed to be used 
with any Amiga with two disk drives and 512K (or more) 
memory. See the inside back cover for information on how to 
order the companion disk. 

What You Should Know to Use This Book 

This book assumes you're familiar with your Amiga. You 
should know about and feel comfortable using the mouse, disk 
drives, monitor, and keyboard. You should be used to the 
Preferences program. 

General experience using the Amiga CLI (Command Line 
Interface) is also assumed. Use Preferences to assure that you 
can access a CLI by clicking the CLI ON gadget in the Prefer- 
ences program, and then save the new Preferences. When you 
reboot the Amiga, the System Drawer on your Workbench disk 
will have a CLI program icon available. This icon can always 
be used to start a CLI. 

You'll use the CLI to type commands directly into the 
Amiga. If you're not familiar with the CLI, you should review 
your Amiga system documentation. Some of the commonly 
used CLI commands needed by programmers are discussed I j 

with examples, but if you want a complete explanation of the ' — ' 

CLI, you should consult the AmigaDOS Manual published by 
Bantam Books. | i 

The AmigaDOS Manual also contains a very good presen- ' — ' 
tation on the Metacomco assembler and linker. Readers are also 
assumed to be familiar with binary and hexadecimal numbers j j 

as well as how to use a text editor (such as MicroEmacs, pro- ' — ' 

vided with Amigas on the Extras disk) or word processor pro- 
gram to type in source code. Some acquaintance with either I i 
MC68000 machine language or machine language on some ' — ' 

xiv |_J 
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other microprocessor will be helpful, but not essential. Those 
with a good background in machine language should be able 
to skip over some of the beginner-oriented sections and di- 
rectly approach the Amiga programming information. 

What You Should Have to Use This Book 

You need an Amiga (any model) with two disk drives and at 
least 512K. Expanded memory to one megabyte or more is al- 
ways a great convenience, since a large ramdisk speeds up file 
access. A printer is also convenient for reading complete pro- 
gram listings, but not essential. 

You should have the Amiga VI. 2 Enhancer software pack- 
age that includes the Extras disk. The Extras disk has a high- 
quality text editor for program source code entry and editing, 
called MicroEmacs (referred to in this book as Emacs). It is a 
variation of a widely used text editor. All of the programs in 
this book assume the use of VI. 2 Amiga operating system, 
which is also part of the Enhancer package. 

If you do not have the Enhancer package, you can get it 
from your Amiga dealer. VI. 2 is the latest version of the op- 
erating system at the time of this writing. 

You also need an Amiga-compatible macroassembler and 
linker. At the time of writing this book there are several popu- 
lar assemblers: 

• The Metacomco assembler package 

• ASM68010 

• The Manx C compiler 

The Metacomco assembler package. The Metacomco as- 
sembler package includes the AmigaDOS Developer's Manual, 
which contains assembler and linker documentation. This 
information is now reprinted in the AmigaDOS Manual, avail- 
able separately. 

Included in the package, along with the Metacomco assem- 
bler, is the Amiga linker (named ALINK). The Metacomco pack- 
age also contains the official Amiga include files, which consist 
of numerous symbol definitions and small macros and subrou- 
tines. These files are large and heavily commented. They have 
been reprinted in the ROM Kernel manuals (see below). 

This package also provides AMIGA.LIB on disk. 
AMIGA.LIB is a large file of program code and symbol defini- 
tions provided for use with ALINK. Because the programs in 
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this book only use the simplest applications of linking, i 

AMIGA.LIB is not used. Programmers who intend to work be- I — I 

yond the scope of this book with advanced linker features will 

be well advised to have the Metacomco package. Even when i i 

using the Metacomco system, the type-in files in this book will I — I 

be required for use with the book's programs. The included 

files are not used here because of their size and enormously j i 

complex scope. L — I 

ASM68010. ASM68010 is an Amiga assembler with a 
built-in linker suitable for the simple linking tasks required by 
programs in this book. The ASM68010 macroassembler (named 
ASM) is provided on the companion disk for this book. Also 
provided on the disk are all the files and program listings in 
this book. The book-disk is an alternative assembler develop- 
ment package because it also has the necessary include files in 
precisely the format required by the book's programs. 
ASM68010 has the advantage of also being fully compatible 
with the MC68010 microprocessor (a slightly more advanced 
version of the MC68000), which many Amiga programmers 
have substituted for their systems' MC68000s (the two are in- 
terchangeable on the Amiga). 

The Manx C compiler package. The Manx C compiler 
package includes an Amiga assembler and linker. Once again, 
the files in the book have to be typed in to be used with the 
Manx C assembler. Use of the Manx C compiler's assembler 
will not be covered in this book. 

The only other thing you may desire to get the most out 
of this book is more Amiga technical documentation. This 
book cannot substitute for the official Amiga publications, but 
they're not necessary to get started. Here's a partial list of re- 
lated books. They contain a wealth of Amiga programming 
information: 

• Programming the MC68000 (Sybex) 

• Amiga ROM Kernel Manuals (Addison-Wesley) covering: j 
Intuition — 
Libraries and Devices 
Hardware 
Exec 

• The AmigaDOS Manual (Bantam Books)— official DOS 
reference 
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The following programming guides concentrate mostly on 
C language but can help with Amiga programming concepts: 

• Programming Guide to the Amiga (Sybex) 

• Amiga Programmer's Handbook, Volumes 1 and 2 (Sybex) 

• Inside the Amiga (Sams) 

• Amiga Programmer's Guide (COMPUTE! Books) 

The last volume also has a section specifically on machine lan- 
guage Amiga programming, with some program listings that 
can be easily converted for use with this book's equate and in- 
clude files. The popular Amiga publication, Amazing Comput- 
ing, has also printed a series of beginner-oriented articles on 
MC68000 machine language. 

Machine language is the most detailed way to program 
the Amiga, and the most efficient. This book provides the 
information and organization to help programmers bypass po- 
tential problems and complications of Amiga programming. It 
can stimulate beginners and advanced programmers to exploit 
the speed and efficiency of machine language to harness the 
power of the Amiga. With some concentration, study, and 
practice, you should find machine language Amiga program- 
ming a straightforward and effective way of expressing your 
Amiga applications. Since the Amiga is such a complex ma- 
chine, no single book about it can be truly complete. Through- 
out the Amiga Machine Language Programming Guide, you'll 
find references to additional Amiga programming information 
to guide you in experimenting beyond the specifics of this 
book. 
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CHAPTER 1 

The MC68000 Architecture 



The Chip Family 

The purpose of this chapter is to familiarize you with the 
MC68000 microprocessor so that you'll be able to read the 
program listings throughout the book. The following chapters 
provide practical instruction sequences using the most com- 
mon MC68000 instructions, while this chapter presents a brief 
overview of the MC68000 and its instruction set. For further 
information, you should also consult the MC68000 manual in 
Appendix A. 

If you're a machine language programmer who's already 
familiar with the MC68000, you might want to skip the rest of 
this chapter. 

In the late 1970s, in response to the growing demand for 
greater microcomputer power and speed, Motorola developed 
the MC68000 microprocessor. The company showed foresight 
when they chose not to add functions to their current 
microprocessor, the 6809. Instead, they took a step backward 
and designed a new microprocessor line: the M68000 series. 
The MC68000, first in the new series, has many advanced fea- 
tures and has become the processor of choice in the computer 
workstation market. It has also become popular in the home 
computer market, having been adopted by such manufacturers 
as Commodore, Apple, and Atari. 

The Motorola-designed MC68000 microprocessor is one of 
a family of five closely related microprocessors, including the 
MC68008, MC68000, MC68010, MC68020, and the newest 
MC68030. Their internal operations are very similar and most 
instructions are shared by all of them. The differences in these 
microporcessors are related to the amount of memory each can 
access during a single operation. The MC68008 reads a byte at 
a time, the MC68000 and MC68010 each read one word (16 
bits, two bytes), and the MC68020 and MC68030 both read 
one long word (32 bits, four bytes) in a single operation. 

Since most of the internal operations of the M68000 fam- 
ily take place in 32-bit registers, it's obvious that the MC68008 
has to perform more read operations per instruction than a 
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MC68020; therefore, the MC68008, by its very nature, is 
slower than the other members of its family. 

Because its internal operations use 32-bit registers, the 
MC68000 is sometimes called a 32-bit processor. Because it 
reads memory 16 bits at a time, it is sometimes called a 16-bit 
processor. 

The MC68010 and MC68000 are similar. Both work 
equally well in the Amiga. In the MC68010, some common in- 
structions are faster than MC68000 equivalents. The Amiga's 
performance is snappier with the MC68010 installed. 

The MC68020 and MC68030 are not only faster than the 
MC68000, they also have some new 32-bit instructions that do 
not exist in the MC68000 and the MC68010. These two are 
true computing powerhouses, and they're about four to ten 
times faster than the MC68000. Since they read data 32 bits at 
a time and require more pins, they won't plug directly into the 
Amiga MC68000 socket. The MC68010, on the other hand, is 
electrically compatible with the MC68000. In many cases, re- 
placing a MC68000 with a MC68010 can increase the per- 
formance of an Amiga as much as 15 percent. 

There is one caveat: The early versions of the Amiga op- 
erating system (1.1 and earlier), will not work correctly with 
the MC68010. Version 1.2 of the Amiga operating system 
fixed those problems and will work properly with the 
MC68010. Commodore has always supplied version 1.2 for 
the Amiga 500 and 2000. Amiga 1000 owners without version 
1.2 can purchase it through any Amiga dealer. 

The M68000 series has many advantages over its 8-bit 
predecessors. These include a set of over 200 instructions for 
manipulating 1-, 8-, 16-, and 32-bit data values. The M68000- 
series microprocessors have 16 general purpose registers and 
12 addressing modes. As a result, the Amiga has over 1000 
machine language instruction combinations. 
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The Registers LJ 

The M68000 family microprocessors have 17 32-bit registers, 
16 of which are available at any given moment. There are two j 
types: data (D) registers and address (A) registers, and there are 1 ~- J 
eight of each. The MC68000 also has some specialized regis- 
ters, including the program counter, status register, and condi- j | 
tion code register. Different microprocessors within the family ^ 
may have one or more special system registers. 
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The MC68000, unlike some other microprocessors, does 
not limit the use of these registers. If an instruction can use 
one of the two types of registers, any register of that type may 
be used. For example, you can add any two data registers to- 
gether with an ADD instruction. This provides much greater 
flexibility because there are fewer hardware constraints. 

The data registers. These are used in various ways: in 
arithmetic, as accumulators, as frequently referenced variables, 
and as index values for indexed addressing modes. Any data 
register can be the source or destination of an arithmetic or 
move operation. In the MC68000 processor, these registers 
cannot be used to fetch data from memory (this restriction was 
removed in the MC68020). 

The register names for the data registers are DO, Dl, D2, 
D3, D4, D5, D6, and D7. While these registers are 32 bits in 
size, an MC68000 instruction can limit itself to the lower 8- or 
16-bit portion of a register when necessary. Therefore, the 
data registers can be used to add two bytes, two words, or two 
long words. (See Figure 1-1.) 

Figure 1-1. Layout of the MC68000 data register. 
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All operations performed on data registers set the condi- 
tion code bits. Condition codes are used in branching; for in- 
stance, if the result of an operation is 0, you may want to 
branch to another part of your program. Condition codes, 
which allow the computer to make decisions like this, will be 
discussed in detail later. 

The address registers. These usually contain addresses or 
address constants. They are used as stack pointers, or as point- 
ers to data, lists, or other data structures. Their names are A0, 
Al, A2, A3, A4, A5, A6, and A7. Register A7 is also known as 
the stack pointer, or SP. 
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Figure 1-2. Layout of an MC68000 address register. 
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The MC68000 can perform arithmetic operations on ad- 
dress registers. The most common of these that are performed 
on addresses — such as addition and subtraction — are avail- 
able, but other operations, such as Boolean, are not available. 
Address registers may only be accessed in word and long- 
word quantities (never as bytes). Most operations performed 
on an address register will not set the condition codes. The 
major exception to this is the compare instruction, which will 
be discussed in more detail later. 

One interesting feature of address registers is that when 
they're loaded with 16 -bit values, they're automatically sign 
extended to 32 bits. When a 16-bit value is sign extended to a 
32-bit value, the uppermost bit of the 16-bit value is dupli- 
cated in the 16 upper bits. This means that a 16-bit negative 
binary number will become the same negative number when 
stored in an address register, except that it will be 32 bits long. 
This is helpful for situations in which 32-bit calculations occur, 
and most or all of the data registers are in use. When an 8- or 
16-bit value is stored in a data register, the upper bits of the 
data register are unmodified. On the MC68000, the EXT.L in- 
struction (which will be discussed in detail later) performs this 
conversion on a data register. 

While the address registers of the MC68000 are 32 bits 
long, only the lower 24 bits are used to address memory (the 
high-order 8 bits are ignored). You should still treat addresses 
as 32-bit quantities, however, to insure compatibility with fu- 
ture Amigas (which may contain an MC68020 and, therefore, 
be capable of dealing with 32-bit addresses). 
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Special Registers 

Register A7 is special, as mentioned above. This register was 
chosen by Motorola as the stack pointer, so it's also known as 
SP. Although it can be used just like any other address regis- 
ter, it would not be a good idea to do so. Register A7 normally 
points to the program stack. Many instructions implicitly use 
the SP as part of their operation, such as the instructions to 
call subroutines and to return from subroutines. This register 
must always point to an even word boundary in memory. That 
is, it must always point to the beginning of a 16-bit word, 
such as location 0, location 2, location 4, and so on. To assure 
that this happens, the MC68000 automatically aligns all 
MOVE instructions using the SP. There is additional discus- 
sion of stack operations later on. 

Other special registers include the program counter (or 
PC), the status register (or SR), and the condition code register 
(or CCR) which is normally the lower eight bits of the status 
register. 

The PC is a 32-bit register that points to the next executable 
instruction. Each time an instruction is fetched from memory, 
the MC68000 updates the PC to point to the address following 
the instruction. The address in the PC may be modified by 
some instructions, such as a branch or subroutine call, before 
the next instruction is fetched. Except when a machine lan- 
guage program executes branches, subroutine calls, traps, and 
certain other instructions, the program cannot modify the PC. 

Neither the status register (SR) nor condition code register 
(CCR) are normally referenced directly by a program. 

Condition codes are bits that are tested when a program 
wants to change program flow as the result of some condition. 
The following code compares a data register to the number 10, 
and branches if the data register contains a value larger than 10. 



CMP.L #10,D0 

BGT NEW_L0CATI0N 



COMPARE DO WITH 10, AND 
SET THE CONDITION CODES 
BRANCH IF DO > 10 



The SR is a 16-bit register, and the CCR is the lower 8 
bits of the SR. For this book, only the bottom 8 bits, or the 
CCR will be discussed. The upper 8 bits are used in system 



Chapter 1 



software, and are beyond the scope of this discussion. The sta- 
tus register is depicted in Figure 1-3. 

Figure 1-3. The Status Register. 
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As you probably know, the letters A-F represent the val- 
ues 10-15 in hexadecimal notation. 

% Unused bit of the status register. 

C Carry bit. This bit is set (made equal to 1) when a carry opera- 
tion occurs, and reset (or cleared — made equal to 0) when a bor- 
row operation occurs. These may occur as the result of addition 
or subtraction. For example, say the addition of two 16-bit num- 
bers generates a 17-bit result. The bottom 16 bits of the result 
would be placed in the destination register, and the carry bit 
would be set to 1. 

V Overflow bit. This bit is set when an arithmetic result is too 
large to be stored in a register. An example of overflow is adding 
two very large 32-bit numbers. If the sum of the two numbers is 
greater than the number that can be stored in 32 bits, overflow 
occurs. In this case, the overflow bit would be set to alert the 
program that the result is too big to be stored in a register. 

Z Zero bit. This bit is set when the result of an operation is 0. Any 
nonzero result clears this bit. 

N Negative bit. This bit is set to the value of the most significant 
bit of the result of an operation. A 1 indicates a negative result, 
while a means the result is positive. 

X Extend bit. This bit is used in many Extend instructions, such as 

ADDX. It provides a mechanism for multiprecision arithmetic. j J 

The extend bit is usually set or reset the same as the C bit. ^"^ 

The programmer should use caution programming the sta- 
tus register. The Amiga provides a special system function call 
(GETCC) to read the condition code bits of the status register 
(SR). Only the MC68000 allows user programs to modify this r i 
instruction. For compatibility with the MC68010 and the l^J 

MC68020, Amiga programmers should use the GETCC func- 
tion provided by Commodore. Although this function is not i i 
used in any of the programs in this book, it is similar in many L^J 
respects to some of the system functions that will be discussed 
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in greater detail. Please refer to the appendices or one of the 
Amiga ROM kernel manuals for more details. GETCC is a 
function in the Exec library. 

The Amiga operating system can execute code in supervi- 
sor or user mode. Supervisor mode is used only when it is nec- 
essary to have unrestricted access to all parts of the machine. 
Because the Amiga programmer has been given a wealth of 
operating system calls, few Amiga programmers will feel the 
need to use this mode. Until you become an advanced ma- 
chine language programmer, you'll probably utilize the User 
mode exclusively. 

All of the M68000 family of processors provide additional 
registers only accessible in supervisor mode. On the MC68010, 
these include the vector base register (vbr), the source function 
code register (s/c), and the destination function code register 
(dfc). Supervisor mode also permits access to a second stack 
pointer on all M68000 family machines (this is the seventeenth 
register, mentioned above). The name of this register is the su- 
pervisor stack pointer (ssp). For further information about 
these registers, please consult the Appendix at the back of the 
book, or consult the appropriate Motorola reference manual. 

Memory Layout 

The MC68000 is one of the first microprocessors to provide a 
large linear address space. The M68000 series processors were 
expressly designed to directly address four gigabytes (32 ad- 
dress bits, approximately 4 billion bytes) of data. On the 
MC68000, a byte is a sequence of 8 bits of binary data. A 
word is 2 bytes or 16 bits, and a long word is two words or 4 
bytes, or 32 bits of data. An MC68000 based computer is only 
capable of accessing the first 16 megabytes (24 address bits, 
approximately 16 million bytes) of this address space. Machine 
language programmers should not try to store information in 
the upper 8 bits of an address. Two members of the M68000 
family, the MC68020 and the MC68030, use the full 32 bits 
and can address the entire four gigabytes. Programs using 
those extra 8 bits may fail on a future Amiga computer using 
one of these microprocessors. 

With the continued reduction in the cost of computer 
memory, future Amigas may have many megabytes (millions 
of bytes) of memory. In contrast, the 80X86 microprocessors 
designed by Intel (used in IBM PCs and compatibles) were not 
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capable of linear addressing more than 64K at a time until 
1986 and the arrival of the 32-bit 80386. 

The M68000 family of microprocessors address memory 
differently than other microprocessors. Other microprocessors 
consider addresses to be in low-byte/high-byte form. If you're 
familiar with the 6502 microprocessor, used in many Apple 
computers and all eight-bit Commodore and Atari computers, 
you're probably accustomed to this format. The M68000 fam- 
ily of microprocessors stores addresses in the more natural 
high-byte/low-byte format. 

Words and long words must have even addresses. Your 
word may start at location 0, location 2, and so on. Long 
words must start at locations divisible by four, such as loca- 
tions 0, 4, 8, and so on. The new MC68020 does away with 
this requirement, but the programmers still advise adherence 
to this rule, as programs run faster this way. 

Figure 1-4. Long word 0. 
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As you can see in Figure 1-4, byte 00000000 is the most 
significant byte of word 0. Similarly, word is the most sig- 
nificant word of long word 0. The most significant byte of 
long word 1 would be byte 00000004. 

The first kilobyte, or 1024 bytes, of the address space on 
the MC68000 is reserved for use by the MC68000 processor. 
Although it's beyond our scope to explain each location, it's 
enough to say these locations are reserved as trap and inter- 
rupt vectors. A trap or interrupt vector is an address of a sub- 
routine to execute when the MC68000 recognizes an exception 
(for instance, a divide by zero error, a bus error, or possibly a 
disk interrupt). 

You should become familiar with the MC68000 instruc- 
tions, as well as the organization of memory, through the 
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presentations here and/or a MC68000 manual. During the de- 
sign of machine language programs, you need to decide on the 
proper use of byte, word, and long-word instructions and data. 
Here are some rules of thumb: 

• Text characters (ASCII) are usually in byte form. 

• Integers (—32768 to 32767) are usually in word form. 

• Floating-point numbers (for example, 2.335987) are usually 
long words. 

• Addresses are always long words. 

In a program you may need to have data in various sizes 
to suit the needs of your application. If you plan to store 
pointers to arrays or pointers to other important memory loca- 
tions (variables, for instance) you must store them as long 
words. Text strings are usually byte arrays. 
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Caution: The most common mistake made by 
MC68000 machine language programmers is forgetting to 
be sure that words and long words begin on even-num- 
bered addresses. 

Be sure that words and long words always begin on 
even-numbered addresses. The assembly programmer's 
term for this is that words and long words must be word- 
aligned in memory. Data stored in byte form can be in 
consecutive odd- and even-numbered addresses, and ad- 
dress registers can point to both odd- and even-numbered 
addresses, but if you try to MOVE a word or long word to 
or from an odd address, you'll crash the machine with a 
Guru meditation— #00000003 .XXXXXXXX— an address 
bus error. 

You can be sure you're at an even-numbered address 
at any time by using the EVENPC macro provided later 
in this book. EVENPC should be used every time a string 
of byte data is declared, just to make sure the next ad- 
dress is an even number. When in doubt, use the 
EVENPC macro. 

It's possible to make a mistake by specifying the 
wrong data size in an instruction. At best, unpredictable 
data may be stored; at worst, you'll crash the machine. 
The system may crash immediately from the instruction, 
or possibly later on as a result of writing over an impor- 
tant nearby memory location. Imagine you've laid out 
four important byte-size variables next to each other in 
memory. If you write to the first variable with a long 
word, you'll unintentionally overwrite the other variables. 
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A machine language program consists of a sequence of lines. 
Each line is a machine language statement. 

Format of a Statement 

For Amiga assemblers, most statements follow a general for- 
mat. The exceptions to this rule are the assembler directives or 
pseudo-ops. The term pseudo-op means pseudo operation. A 
discussion of the general format for machine language source 
code follows. You'll find an in-depth discussion of pseudo-ops 
in an upcoming section. 

A line of machine language source code can contain three 
fields; each of these fields is optional. They are: 

• A label field 

• An opcode field and the operands associated with that 
opcode 

• A comment field 

Consider the following example: 
EXLAB: MOVEQ #10,D0 ;SET DO TO BE THE VALUE 10 

In the above example, EXLAB: is a label, MOVEQ is the 

, .. opcode, #10 and DO are operands, and the text following the 

I semicolon is a comment. 

j— I Labels 

1 I A label (also known as a symbol), is a string of alphanumeric 
characters that refers to an absolute or a PC-relative (Program 

n Counter-relative) address. A label may consist of an upper- or 
lowercase ASCII character, a number, a period, or the under- 
score character. The first character of a label may not be a 
n number because the assembler will attempt to parse it as a 
number. Do not use opcodes for labels. 
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The Metacomco Amiga assembler imposes an upper limit j 

of 30 characters on the label. The ASM68010 assembler is more U ~ J 
flexible, but for backward compatibility with the Metacomco as- 
sembler, you should still limit labels to 30 characters. j j 

Unlike opcodes, register names, and assembler directives, 

labels are case sensitive. This means the labels Assem, 

ASSEM, and AsSeM are all different. For consistency, only up- j j 
percase labels will be used in examples. If you don't want case 
sensitivity, use the assembler option -c C. See the section on 
assembler options in the Appendix at the back of this book for 
more information. 

Here are examples of legal and illegal labels: 

Legal Labels 

a Aa R2d2 

FooBar .LI VERY_long_LaBeL.STILL_LEGAL 

_JMAIN 0. ..9 .9 

Illegal Labels Reason 

3.141PI Leading digit 

Bad?Label Illegal character (?) 

quote— notlegal' Illegal character (') 

ADD Has the same name as an opcode 

Some labels are predefined by the Metacomco and 
ASM68010 assemblers. The following is a list of these 
predefined labels: 

Label Definition 

This special label is the value of the location 
counter. The location counter is the assemble-time 
version of the program counter. This symbol can be 
used whenever it's necessary to find out the current 
offset from the beginning of the file. Usually, this 
symbol is used in calculating the length of some 
data. 

The following example shows how * is used to j - 1 

calculate the length of a string. The pseudo-ops [ j 

EQU and DC.B, used in this example, are covered 
in more depth in the next chapter. The label LEN 
will contain the value 20 after the second line has 
been processed. 



* 



STRING: DC.B '20 character string.' 

LEN EQU STRING-* ;GET THE LENGTH OF STRING 
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NARG This special label contains the number of argu- 

ments sent to a macro invocation when the assem- 
bler is processing it. Macros and macro invocations 
are discussed in detail in the next section. 

Register names All register names (dO, DO, dl, Dl, aO, AO, sp, SP, 
pc, PC, and so on) are considered symbols by the 
assembler. All lower- and uppercase versions of the 
registers are set aside by the assembler as reserved 
labels. 

Labels are used in two different locations. The first is the 
label definition, and the second is in a label reference. The 
definition of a label is the location in the program where the 
label is assigned a value. A label reference is any place where 
a label is used to refer to the label's value. 

Label definitions take two forms: A label may be set to a 
value using an assembler directive such as EQU, EQUR, SET, 
or REG; or, it may be an address. The following is an example 
of a label assigned a value with an assembler directive: 

TEN EQU 10 

In the example above, TEN is the label, EQU is the as- 
sembler directive, and 10 is the value. (Assembler directives 
are discussed in detail in Chapter 7.) 

This example assigns the constant 10 to the label TEN. 
This is an example of an absolute label definition. 

When the assembler sees an address label definition, it as- 
signs the current relative address to the label. This address is 
the same as the location counter. This label may be used to 
change the flow of execution or as part of some other calcula- 
tion at the time of program assembly. In other words, an ad- 
dress label definition is a way of accessing a piece of data 
without having to know exactly where its physical address is. 
Since the assembler will automatically manage this infor- 
mation, the programmer is only required to keep track of the 
label that points to the data. This is the most common use of a 
label. In this situation, a label refers to a data location in 
memory or to an address to which the program will jump. 

An address label definition has two formats: If the first 
character of the label starts in column 1 of an input line, the 
label name will terminate either at the first blank character, a 
colon, or at the end of the input line; if the label does not start 
in column 1, the label must be terminated with a colon. Any 
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other form will cause an assembly-time error. 

The following are some examples of address label 
definitions: 



Assume this delineates left margin 



STRING: 



DC.B 



'HELLO',0 



STRING2: 

DC.B 'GOODBYE',0 



A SAMPLE DATA LOCATION WHOSE 
ADDRESS IS 

THE START OF THE STRING 
"HELLO" 

ANOTHER SAMPLE DATA LOCATION 



JUMPHERE: 



LEA 



STRING,A0 



BRA 



JUMPHERE 



A SAMPLE INSTRUCTION 
LOCATION 

THIS INSTRUCTION LOADS THE 
ADDRESS OF THE 
DATA LOCATION STRING INTO 
THE ADDRESS 
REGISTER AO. THIS IS AN 
EXAMPLE OF A 

LABEL REFERENCE. THE CODE 
WILL BE DISCUSSED 
IN DETAIL LATER. 

ANOTHER EXAMPLE OF A LABEL 

REFERENCE. THIS 

REFERENCE MAKES THE PROGRAM 

CHANGE ITS 

EXECUTION DIRECTION, AND 

START EXECUTING 

AT THE LOCATION 'JUMPHERE* 

Normal labels, as described in the previous paragraphs, 
may be externally defined or referenced. The assembler 
directives XDEF and XREF signal the assembler that a label is 
accessible outside the file (XDEF), or the label is defined in an- 
other file (XREF). If these directives are not used, then labels 
are only meaningful within the current assembly input file and 
must be defined there. The latter method is used in all pro- 
grams. None of the examples seen here use the XREF or XDEF 
directives. 

Another type of label, known as the local label, has a much 
shorter life span. A local label has the form n$, where n is a 
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sequence of decimal digits. Some examples are 3$, 1$, and 10$. 

Local labels exist only between the definition of two nor- 
mal labels. This means that a local label must follow a normal 
label definition, and it ceases to exist at the next definition of a 
normal label. 

The advantage of local labels is that they may be rede- 
fined and reused after each normal label definition. Local la- 
bels are never used outside the range of the two normal label 
definitions. Standard assemblers cannot detect which local la- 
bel is being referenced in that case. 

The following example shows local labels: 



GOES TO LABEL TEST 

GOES TO THE NEXT STATEMENT 

LEGAL INSTRUCTION (GOES TO NEXT 
STATEMENT) 

GOES TO THE STATEMENT BELOW 

ILLEGAL (THERE IS NO LABEL TO GO TO 

FROM HERE) 

THE LABEL 2$ IS NOT DEFINED AFTER THE 

LABEL 

TEST. 



left margin 




START: 




BRA 


TEST 


F00 




BRA 


1$ 


1$: NOP 




BRA 


2$ 


2$: 




TEST: BRA 


1$ 


1$: 




BRA 


2$ 



QUIT BRA START 



n 

n 
n 
n 



Opcode and Operand Formats 

The second field of a line of source code is usually the 
MC68000 instruction mnemonic, or opcode, and the cor- 
responding operands (opcode is a contraction of operation and 
code). MC68000 mnemonics always begin indented at least 
one space from the beginning of the line. This distinguishes an 
opcode from a label. The general format of instruction opcodes 
is a set of three or more ASCII characters, possibly followed 
by a period and a size specifier. These opcodes were defined 
by the MC68000 design engineers. 

An opcode is a shorthand definition of a machine opera- 
tion. For example, the opcode that was chosen by the 
MC68000 engineers to represent the instruction to "perform a 
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binary ADDition of two operands" was ADD. As a second ex- 
ample, the opcode LEA stands for "Load Effective Address" 
(note that the capitalized letters denote the characters used in 
forming the mnemonic). This part of an opcode is sometimes 
called the base, because the opcode refers to the base or basic 
part of the operation. It does not necessarily refer to the size 
of the instruction. The base usually has some form of size 
specifier appended. When a size specifier does not exist on a 
MC68000 instruction, the implied size is usually a 16-bit word 
opcode (an opcode that expects to perform an operation on a 
word-sized operand, symbolized by the letter W). 

The following size specifiers are used in the MC68000 
machine language: 

B Signifies a byte-sized opcode. 

W Signifies a word-sized opcode. 

L Signifies the long-word sized opcode. If this size specifier is ap- 
plied to a branch instruction, it tells the assembler to force a 16- 
bit relative offset, allowing your program to branch about 32K 
forward or back, relative to the current location specified by the 
program counter. 

S This size specifier is only applied to branch instructions and tells 
the assembler to force an 8-bit relative offset. 

A complete list of the opcodes and their various formats 
appears in Appendix A. Some of the most important opcodes 
will be discussed later in this chapter. 

The second part of the second field in a line of source 
code consists of the operand(s). Opcodes on the MC68000 may 
be accompanied by zero, one, or two operands. Operands are 
the data on which the opcode operates (remember that opcode 
is a contraction of operation and code), or a reference to the 
data that the instruction uses. | i 

Two-operand opcodes. Usually, when an opcode needs 
two operands, it's obvious when you look at the meaning of 
the opcode. MOVE and ADD, for instance, require two [ j 
operands. The first would require two locations, and the sec- 
ond would require two quantities. 

When an opcode requires two operands, the first is the ! ! 

source operand and the second is the destination operand. 
Source and destination make sense in this context because, as 
in a MOVE instruction, the source operand gets moved to a I ! 

destination. The ADD instruction adds a source operand to a 
destination operand. MC68000 assemblers do not distinguish 
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between upper- and lowercase opcodes. For the sake of consis- 
tency, all opcodes in this book are in uppercase. This, how- 
ever, is not a sign that opcodes must be written in this 
manner. 

Zero- and one-operand opcodes. When only one operand 
is involved, it is considered the destination operand. Gener- 
ally, an opcode that requires a single operand performs only 
one function, such as pulling a value from the stack, storing a 
value, comparing a value, and so on. An opcode that requires 
no operand is one that performs a function within the micro- 
processor itself, or the NOP (No OPeration) opcode, which 
simply tells the computer to do nothing. 

Operands and addressing modes will be discussed in 
greater detail later in this book. 

The Comment Field 

In many respects, comments are the most important part of 
any program. This includes machine language as well as high 
level languages such as C, Pascal, or BASIC. Comments are 
just one more aspect of good programming practice. Most of 
the life of a program is actually maintenance, such as debug- 
ging and adaptation to new situations. Comments are essential 
to this process. 

There are three ways to denote a comment: 

• When the first character of a line is an asterisk, the entire 
line is treated as a comment. 

• Any time a semicolon is encountered, the rest of the line is 
treated as a comment. 

• Any characters at least one space after the last operand on a 
line are considered comments (ASM68010 assembler only). 

A comment signals the assembler to ignore the rest of the 
current line and to proceed to the next line. 

Because the third method of denoting a comment is not 
standard, it should be avoided if you are planning to use an 
assembler other than the ASM68010 assembler. 
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Explaining machine language instructions before explaining 
the addressing modes they employ is almost as difficult as ex- 
plaining the addressing modes first, and then the instructions 
afterward. If you're a beginner, you may need to read this and 
the next chapter more than once. The first time, try to read for 
the definitions of terms. The second time through, you'll begin 
to understand the concepts involved. 

The MOVE Instruction 

The most fundamental instruction in the M68000 family is the 
MOVE instruction. It performs most of the memory and regis- 
ter handling in almost any M68000 program. 

Since it is so heavily used, and is the first opcode dis- 
cussed here, the discussion will be much more detailed than 
the discussion of opcodes to follow. Even if you're not inter- 
ested in the MOVE opcode at the moment, it would be a good 
idea to read this section for the background material. 

MOVE is actually a group of related instructions. It per- 
forms the function of LOAD and STORE instructions found in 
many other microprocessors (such as LDA or LDX on the 6502 
microprocessor, as well as STA or STX). The MOVE instruc- 
tion requires two operands — a source and a destination. 

The MOVE instruction uses any of the three standard | j 

sizes, byte (B), word (W), or long word (L). On the MC68000, l — J 
the standard MOVE instruction may use any of the legal ad- 
dressing modes for both the source and destination. (Address- I j 
ing modes will be discussed later in this book.) Many MC68000 ' — ' 
assembly programmers take this capability for granted — until 
they have to write assembly code on a different microprocessor, j I 
such as the 8086, on which the MOVE instruction does not ^ — f 

operate in all modes. 

With some of the following examples, you can recognize 
the breadth of utility of the MOVE instruction. Here are some 
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examples of its many forms: 
MOVE.B D1,D2 

MOVE INFO,Dl 



MOVE.W D0,A0 



MOVE.L D1,D2 
MOVE.W #1,FLAG 
MOVE.L A0,-(SP) 



MOVE.W (SP)+,D6 



MOVE.L D2,(A0) 
MOVE.W VAR1,VAR2 



Move one byte from data register Dl 
to data register D2. 
Move one word from location INFO 
to data register Dl. Note: This uses 
the implied W size specifier. As a re- 
sult of using this form of the instruc- 
tion rather than the MOVE.W 
(below), the upper 16 bits of the data 
register won't change. This may result 
in a sign change (from positive to 
negative, or negative to positive) of 
the value moved. The sign will be 
that of the value previously in the 
register. 

Move a word from data register DO to 
address register AO. Note: When the 
MOVE instruction loads an address 
register with a word value, the 
MOVE instruction automatically sign- 
extends the 16-bit value to a 32-bit 
value, thus, retaining the sign of the 
value moved, and consequently de- 
stroying whatever data had been in 
the upper 16 bits of the address 
register. 

Move a long word (32 bits) from data 
register Dl to data register D2. 
Set the data location at the label 
FLAG to the value of 1. 
Move the long word in address regis- 
ter AO to the top of stack. Note: This 
is the equivalent of the PUSH instruc- 
tion commonly found in other com- 
puters. This will be discussed later in 
more detail. 

Move a word from the top of stack to 
data register D6. Note: This is the 
equivalent of the POP instruction 
commonly found in other computers. 
This will be discussed later in more 
detail. 

Move the contents of data register D2 
to the address in address register AO. 
Move the data at label VAR1 to the 
location of label VAR2. 
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MOVE.B 5(A0,D0),0(SP,A1) A move instruction with complex ad- 
dressing modes. 

MOVE.W 10(PC),8(A1,D1) A move instruction with complex ad- 
dressing modes. 

In addition to the standard MOVE instruction, there is a 
faster subset of the most-used forms of MOVE. 

MOVEQ. A variation of MOVE to put immediate data di- 
rectly into a register. Immediate data is data specified on the 
same line as the MOVE instruction, as in MOVE.W #1,FLAG 
in which #1, is the immediate data moved to FLAG. 

MOVEQ is specialized. It can only move an 8-bit numeri- 
cal value into the data registers. The key thing to remember is 
that although only 8 bits are specified, they're sign extended 
to a full 32 bits before the data register is loaded. Here are 
some examples: 

MOVEQ #3,D1 Move the value 3 into data register Dl. 
MOVEQ #T,D0 Move the ASCII character ? (hexadecimal 

value #$3F) into data register DO. 
MOVEQ #$FF,D7 Move the value $FFFFFFFF (the sign-extended 

version of #$FF) into data register D7. 

The advantage of MOVEQ is that it is the fastest instruc- 
tion for moving a small number into a register. It is used in 
many of the programs in this book to clear a data register, as 
in 

MOVEQ #0,D0 

This is faster than the following instruction, which accom- 
plishes the same thing: 

CLR.L DO 

MOVEM. A single MOVEM (MOVE Multiple. registers) j_J 
instruction can move more than one register to or from the 
stack. This instruction is similar to MOVE, but it has a differ- - - -- 
ent set of operands. The operands required by MOVEM are a j j 
register list and memory address. A register list is a set of reg- 
ister names that specify which registers are to be copied to the — 
data locations, or from the data locations to the registers. Here j j 
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are some examples of register lists: 



DO 

D0-D3 

D2-D5/A0 

D5-D7/A3-A6 

D6/A6 



Data register DO only. 

Data registers DO, Dl, D2, D3. 

The registers D2, D3, D4, D5, AO. 

The registers D5, D6, D7, A3, A4, A5, A6. 

The registers D6 and A6. 



Two items separated by a dash (-) indicate an inclusive 
list of registers, and the slash (/) is used to separate register 
names or register lists. 

When storing a list of registers to memory, the following 
addressing modes are allowed (more information on address- 
ing can be found in Chapter 4): 

(An) -(An) dl6(An) 

d8(An,Rn) ABS.W ABS.L 

When loading a list of registers from memory, the follow- 
ing addressing modes are allowed: 



(An) 

d8(An,Rn) 

dl6(PC) 



(An)+ 

ABS.W 

d8(PC,Rn) 



dl6(An) 
ABS.L 



Here are some examples: 
MOVEM.L D0-D1/A0-A1,(A2) 

MOVEM.L D0-D7/A0-A6,-(SP) 

MOVEM.L (SP)+,D0-D7/A0-A6 



MOVEM.L DATAREGS,D0-D7 



Moves DO, Dl, AO, Al to the 
address in address register A2. 
This pushes all registers except 
A7 onto the stack. 
This pulls all registers except A7 
from the stack. This is the op- 
posite of the operation immedi- 
ately above. 

Moves data from the location 
marked by the label 
DATAREGS into the data 
registers. 

In MC68000 machine language, the opcode MOVE allows 
all of the legal addressing modes for either of its operands. 
MC68000 machine language provides extra error checking 
when restricted versions of the instruction are used. Most 
commonly, the restricted version of the opcode is the opcode 
followed by I, A, and sometimes M. 
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• The I appendage implies that the source operand must be an 
immediate operand. 

• The A appendage implies that an address register is the 
destination. 

• The M appendage implies that both the source and destina- 
tion will be memory addresses. 

For the MOVE instruction, only MOVEI and MOVEA are 
acceptable. The M appendage doesn't exist for the MOVE in- 
struction. It would conflict with the MOVEM instruction de- 
scribed above. 

Here are some legal examples of the MOVEA, and MOVEI 
instructions: 



MOVEI #10,D0 

This is the same as: 

MOVE #10,D0 

or: 

MOVE.W #10,D0 
The instruction: 

MOVEA JUNK.A0 



LOAD IMMEDIATE VALUE 10 INTO DO 



MOVE CONTENTS OF MEMORY LOCATION 

JUNK INTO A0 



is the same as: 

MOVE.W JUNK.A0 
Here are illegal examples of MOVEA and MOVEI: 



MOVEI.L 
MOVEA! 



JUNK,(A0) 
(A0)+,(A1)+ 



THE SOURCE OPERAND ISN'T IMMEDIATE 

THE DESTINATION ISN'T AN ADDRESS 
REGISTER 



The MOVEA instruction is often confused with the LEA 
(Load Effective Address) instruction. This is due to the misin- 
terpretation of the MOVEA instruction as MOVe Effective Ad- 
dress, which is incorrect. The real meaning of MOVEA is 
MOVE to Address register. 

The LEA Instruction 

The LEA (Load Effective Address) instruction loads the ad- 
dress of a labeled location in memory into an address register. 



U 
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Normally, every time an instruction is executed, the 
microprocessor reads the instruction, calculates the addresses 
of the operands, uses these addresses to get the real operands, 
performs the specified operation on the source operand, and 
finally, stores the result in the specified destination operand 
address. 

When the source or destination operand is a register, the 
microprocessor has a very easy time figuring out where the 
data operand is. Other times, the MC68000 microprocessor 
must precalculate the actual memory address of the data that 
will be used in the instruction. Once the address has been cal- 
culated, the MC68000 microprocessor can fetch the data from 
that address and perform the operation. This calculated ad- 
dress is called the effective address of an operand. 

It is useful to have the effective address calculated and 
stored for later use in the program. This is the most common 
application of the LEA instruction. It calculates the address of 
the source operand and loads the calculated address into an 
address register. For example, you might have a labeled loca- 
tion in your program which is the beginning of an array of 
data. You might want to move the starting address of the array 
into an address register this way: 

LEA ARRW.A1 

To demonstrate the difference between MOVE and LEA, 
examine the following lines. For the sake of the example, say 
the label ARRA¥ is at memory location 1A007A: 



MOVE.L ARRW.A1 



LEA.L ARRW,A2 



MOVES THE CONTENTS OF MEMORY LOCA- 
TION 1A007A TO Al 

MOVES THE NUMBER 1A007A TO A2 



LEA always moves a long-word address. That address can 
then be used as part of another instruction as in the following 
source code: 

LEA.L ARRW.A2 

MOVE.L (A2),A1 

This source code would assemble into a program that 
loads the address of ARRAY into register A2, and then moves 
the value in the memory location labeled ARRAY into register 
Al. 

The operation performed by LEA can be accomplished in 
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another way, using the MOVE or MOVEA instruction: 

MOVE.L #ARRAY,A2 
or 

MOVEA.L #ARRAY,A2 
are equivalent to the LEA instruction: j I 

LEA ARRAY.A2 

These three instructions all load the 32-bit address of the 
label ARRAY into register A2. These fo r ms are equivalent, but 
not identical (they result in different object codes, with LEA 
executing faster). 

The LEA instruction can use many of the MC68000 ad- 
dressing mode calculations, including: 

(An) (An) + -(An) 

dl6(An) d8(An,Rn) ABS.W 
ABS.L dl6(PC) d8(PC,Rn) 

Here are some examples of the use of the LEA instruction: 

LEA (A1),A2 Moves Al to A2. 

LEA 1(A2),A2 The address in register A2 is incremented 

by one and loaded into register A2. 

LEA.L $AA(A2),A3 Adds hexadecimal number $AA to A2, and 

loads the sum into A3. 

LEA 0(PC),A2 This instruction loads the address of the 

next instruction (located in the program 
counter) into A2. 

LEA.L — 4(PC),A0 This line of source code loads its own ad- 
dress into AO. 

LEA 0(A2,D2.L),A0 Adds the contents of registers A2 and D2 

and the number 0, and stores the sum in j j 

AO. •— J 

When programming, you can easily tell when you need to , - ( 

use LEA and when you need MOVEA instead. Always use the 1 1 

LEA instruction rather than the MOVE immediate form. This 

practice makes programs easier to read and debug. . . 

u 

The ADD and SUB Instructions 

The MC68000 microprocessor provides a basic set of j j 

arithmetic functions. These are addition, subtraction, multipli- ' — ' 
cation, and division. All four of these arithmetic functions are 
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available for 16-bit values. Addition and subtraction can be 
used for 8- and 32-bit values as well. 

There are three ADD binary and three SUBtract binary in- 
structions. The MC68000 microprocessor can ADD: 

• Any data value to any data register 

• Any data register to any memory location 

• Any word or long-word value to any address register 

• Any immediate value to any data location 

There's also the ADDQ instruction, which stands for ADD 
Quick. It allows very rapid addition of small integer values be- 
tween one and eight. 

Similarly, the MC68000 can subtract: 

• Any data value from any data register 

• Any data register from any data location 

• Any word or long-word value from any address register 

• Any immediate value from any data location 

The SUB instruction also has the SUBQ (for SUBtract 
Quick) form for small integer values between one and eight. 

One additional note: When adding or subtracting a 16-bit 
(word) value from an address register, the word value is auto- 
matically sign extended first and treated as a signed 32-bit 
value. 

Here is a list of some of the possible ADD and SUBtract 
combinations: 



ADD 



D4,D5 



ADD.L 


(A0),D4 


ADD.B 


D4,BVAL 


ADD.W 


#12345,A1 


ADD.W 


#$3039,A1 


ADD.W 


D4,A2 


ADDQ.L 


#1,D0 



Add the word in register D4 to the word in 
register D5. Remember that this operation 
sign extends the 16-bit word to 32 bits. This 
also happens in the next example. 
Find the long word in the address refer- 
enced by AO and add it to D4. 
Add the byte in D4 to the data at the ad- 
dress at label BVAL. 

Add the decimal constant 12345 ($3039 
hexadecimal) to address register Al. 
Same as last example, but in hexadecimal. 
You must use a dollar sign ($) to indicate 
hexadecimal. 

Add the word in D4 to A2. This will result 
in sign extension. 

Add one to DO. This is like an increment in- 
struction on other microprocessors. 
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ADDQ.W #4,D0 



SUB.W #55,A0 
SUB.B D0,D4 



SUBQ.W #3,WVAL 



ADD.L DO,DO 



Add four to DO. This allows incrementing by 
the value 4 (or any other integer) instead of 
1. 

Subtract the value 55 from the value in reg- 
ister AO. 

Subtract the byte contained in DO from the 
value in D4. Remember that the carry flag is 
also set if a borrow occurs. 
Subtract the value 3 from the word at the 
location labeled W\AL. This is a more gen- 
eral version of the decrement instruction 
found in other computers. 
A fast arithmetic shift left by one bit. This 
effectively multiplies the value in register 
DO by two (the same action as if all bits in 
the long word in register DO were shifted 
one location to the left). 



The MUL and DIV Instructions 

The MC68000 microprocessor doesn't have a complete set of 
8-, 16- and 32-bit arithmetic multiply and divide instructions. 

The microprocessor can perform 16-bit X 16-bit multipli- 
cation, yielding a 32-bit product. It can also divide a 32-bit 
dividend by a 16-bit divisor to yield a 16-bit quotient stored in 
the lower 16 bits of the destination register. If there is a re- 
mainder, it will be stored in the upper word of the destination 
register as a result. 

Multiplication. The two multiplication instructions are 
MULS (MULtiply Signed) and MULU (MULtiply Unsigned). 
They can take the following as multiplier operands. 

• As a source: 

A data register 

An immediate value 

A memory location 

• As a destination: 
A data register 

Some sample multiplications are: 

MULS #5,D0 Multiply DO by five (signed) and store the prod- 

uct in DO. 

MULU DATA,D2 Multiply the word at location DATA with the 

contents of D2 (unsigned) and leave the product 
inD2. 



U 

u 
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After multiplication, the destination data register contains 
a full 32-bit result. 

Division. The two divide instructions are the DIVS (Di- 
vide Signed) and DIVU (DIVide Unsigned). They divide a 32- 
bit value in the destination register by a 16-bit value specified 
by the source operand. 

The result of the division comes in two parts: the quotient 
and the remainder. After performing the division, the micro- 
processor places the quotient in the lower 16 bits of the des- 
tination register and the remainder in the upper 16 bits of the 
same register. 

Because some division operations will result in a quotient 
too large to fit in the lower 16 bits of the destination register, 
an overflow condition may occur. When overflow takes place, 
the overflow status bit in the status register is set to 1. 

If Dl contains the value 26 and DO contains the value 5, 
the following code: 

DIVS D0.D1 ;SAME AS S/MNG Dl = Dl / DO 

stores a value of 5 in the low word of Dl, and a value of 1 in 
the high word of Dl. 

Here are more examples: 

DIVS #5,D0 Divide DO by five and store the results in DO. 
DIVU D2,D3 Divide the value in register D3 by the value in reg- 
ister D2 and store the results in D3. 

Since the MC68000 does not provide a 32-bit X 32-bit 
multiply or divide instruction, this operation must be done in 
software. Below is an example of a 32-bit X 32-bit multiplica- 
tion routine yielding a 32-bit result. Note that an extra multi- 
ply must be performed to yield a full 64-bit result. 

* MULTIPLY A 32-BIT DO BY A 32-BIT Dl. PLACE THE RESULT 

* OF THE MULTIPLY IN D2. USE D3 AND D4 AS TEMPORARY VALUES. 

* THIS IS A SIGNED MULTIPLY , SO THE SIGN PRESERVATION CODE 
IS ALSO IN THIS EXAMPLE 



* 



MOVEQ #1,D4 
TST.L DO 



THE TEMP USED TO HOLD THE SIGN 

OF THE RESULT 

CHECK THE FIRST 32-BIT VALUE FOR 

NEGATIVITY 



BGE POSITIVE_FIRST 

NEG.L DO ; MAKE POSITIVE FOR MULTIPLY 

NEG D4 ; KEEP SIGN 

POSITIVE_FIRST: 
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TST.L 


Dl ; 


CHECK THE SECOND 32-BIT VALUE FOR 


U 




) 


NEGATIVITY 


BGE 


POSITIVE-SECOND 






NEG.L 


Dl ; 


MAKE POSITIVE FOR MULTIPLY 


i ( 


NEG 


D4 


KEEP SIGN 


u 


POSITIVE-SECOND: 




'■*— ..J 


; NOW MULTIPLY 2 POSITIVE 32-BIT NUMBERS 




MOVE.W 


D0.D2 




G 


MULU 


D1,D2 


MULTIPLY LOW16*LOW16 


MOVE.W 


D0,D3 






SWAP 


DO 


SWITCH TOP/BOTTOM REGISTER HALF 
OF DO 




MULU 


D1,D0 


MULTIPLY HIGH16*LOW16 




SWAP 


Dl 


SWITCH TOP/BOTTOM REGISTER HALF 
OFD1 




MULU 


D1.D3 


MULTIPLY LOW16*HIGH16 




ADD! 


D0,D3 


COMBINE THE MIDDLE 32 BITS OF THE 
64-BIT MULTIPLY 




SWAP 


D3 






CLR.W 


D3 


PREPARE TO COMBINE LOWER 32 BITS 




ADD.L 


D3.D2 


COMBINE THE LOWER 32 BITS OF THE 
64-BIT NUMBER 




TST 


D4 


• NEED TO CHANGE THE SIGN?? 




BGE 


EXIT 


;NO 




NEG.L 


D2 


; YES, MULTIPLY BY -1 




EXIT: 








* REGISTER D2 NOW CONTAINS TH 


E 32-BIT RESULT 




* AND REGISTERS DO, Dl, D3, D4 CONTAIN GARBAGE 




* THIS SEQUENCE DOES NOT SET 


UP THE OVERFLOW BITS 





Logical Instructions (OR, EOR, AND, NOT, and NEG) 

By now you should be getting the idea of how MC68000 in- 
structions are organized. The logical instructions (AND, OR, 
EOR, NEG) operate directly on registers or memory, and on all 
three sizes of data (byte, word, and long word). 

Logical operators affect data bit-by-bit. In order to under- 
stand their operation, it is necessary to think of values in 
terms of binary numbers. You're probably already familiar 
with logical operators and the binary number system. If not, 
you should consult a text such as Machine Language for Begin- 
ners from COMPUTE! Publications, or Assembly Language Pro- 
gramming from Howard W. Sams. 

The logical operators operate by very special rules in the 
MC68000 microprocessor. For instance, the source operand of 
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an EOR must be a data register. Also, the AND and OR in- 
structions cannot use an address register, and either the source 
or destination must be a data register 

The NOT and NEG instructions are not as widely known 
as the others. They each take only one operand — which may 
not be an address register. NOT reverses all the bits in the 
destination and NEG performs a two's compliment NEGation 
operation, changing the sign of a signed integer. 

Below are truth tables for the AND, OR, EOR, NOT, and 
NEG instructions, as well as some examples of each. 

Logical AND (AND). 

Binary Hexadecimal 

AND = 11001010 CA 

AND 1 = AND 10111000 B8 

1 AND = — 



1 AND 1 = 1 10001000 88 

Program example: 

AND.W #1,D0 ; CHECK FOR ODD OR EVENNESS (IN A 

WORD) 
BEQ WASEVEN ; BRANCH TO LABEL WASEVEN, IF IT WAS 

;EVEN 
AND.L #$FFFFFFFE,DO ; MAKE DO EVEN 

Inclusive OR (OR). 

Binary Hexadecimal 

OR = 11001010 CA 

OR 1 = 1 OR 10111000 B8 

1 OR = 1 — 



1 OR 1 = 1 11111010 FA 

Program examples: 

0R.L D1,D0 ;UNI0N THE TWO LONG-WORD REGISTERS 
0R.W #1,D3 ;MAKE D3's LOW WORD ODD 

Exclusive OR (EOR). 

Binary Hexadecimal 

EOR = 11001010 CA 

EOR 1 = 1 EOR 10111000 B8 

1 EOR = 1 — 



1 EOR 1 = 01110010 72 
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EOR.L DO.DO ;SET DO TO 

EOR.B DO.VAL ;EOR DO WITH BYTE AT LOCATION VAL 
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Program examples: 

OR.L DO.DO ;! 
3R.B DO.VAL ;] 

Logical NOT (NOT). | \ 

Binary Hexadecimal 

NOT = 1 NOT 11001010 CA 

NOT 1 = I 

00110101 35 

Program example: 
NOT.B FLAG ;INVERT THE BITS AT BYTE LOCATION 'FLAG' 
Arithmetic NEGate (NEG). 

Program examples: 

NEG.L D2 .MULTIPLY D2 BY -1 

NEG.W RESULT ;MULTIPLY WORD AT LOCATION RESULT BY -1 

Shift and Rotate Instructions (LSL, LSR, ASL, ASR, 
ROL, and ROR) 

These instructions perform Logical Shifts Left (LSL), Logical 
Shifts Right (LSR), Arithmetic Shifts Left (ASL), Arithmetic 
Shifts Right (ASR), Rotations Left (ROL), and Rotations Right 
(ROR). 

Shifts and rotations have three different forms. The first 
two forms involve multiple shifts (shifting or rotating the bits) 
in a data register. The first of these two forms uses an immedi- 
ate value between and 7 to specify the number of shifts (this 
is called a shift count — a value of causes a shift of 8 bits). 
The second form uses a data register to specify the number 
shift count. The six least significant bits of the source register 
specify a shift count of between and 63 (a value of causes 
a shift of 64 bits). 

The destination operand must always be a data register. 

The third form performs a shift or rotate of only one bit 
position on an operand in memory, rather than a data register. 
The first two forms may shift or rotate data registers contain- 
ing byte, word, or long-word values, but single-bit shifts are 
restricted to word-sized (16-bit) values. 

The following diagrams show the operation sequence for 
a single-bit shift or rotate. In these examples the letter C 
stands for the carry bit and X stands for the extend bit (both of 

32 



n 
n 
n 
n 
n 



Amiga Machine Language Programming 



these bits are in the status register). 

The figures below represent an entire 32-bit register. The 
arrows in these diagrams indicate the direction in which data 
moves within the register. During shifts and rotates, the last 
bit on the left or right is pushed out of the register. The dia- 
grams indicate whether that bit is lost or stored in the X and C 
bits of the status register. 

When discussing bits on the MC68000 family, the high- 
order bit is bit #7 for a byte, #15 for a word, and #31 for a 
long-word value. 

Arithmetic Shift Left (ASL). The first shift is ASL. A 
graphic depiction of this instruction can be found in Figure 3- 
1. Each bit is shifted to the left. The high-order bit (in this 
case, Bit 31) is shifted into the C and X bits in the status regis- 
ter, and a is shifted into bit at the far right. The overflow 
bit is set if a sign change occurs during the shift. 

Figure 3-1. Arithmetic Shift Left (ASL) 
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Note: The overflow bit indicates if any sign changes 
occurred during the shift. 



Examples of Arithmetic Shift Left: 

ASL.L #2,D0 ;SHIFT LONG WORD IN DO LEFT BY TWO BITS 
ASL D0.D1 ;SHIFT WORD IN Dl LEFT BY SHIFT COUNT (IN DO) 
; BIT POSITIONS 

Arithmetic Shift Right (ASR). Figure 3-2 shows the ac- 
tion of an ASR instruction. Each bit is shifted to the right. Bit 
is shifted into the C and X bits in the status register. The 
sign bit is duplicated from the high-order bit of the shift (in 
this case, Bit 31). 
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Figure 3-2. Arithmetic Shift Right (ASR) 
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Examples of Arithmetic Shift Right: 



ASR.L 
ASR 



#2,D0 
D0,D1 



SHIFT LONG WORD IN DO RIGHT BY TWO BITS 
SHIFT WORD IN Dl RIGHT BY SHIFT COUNT (IN DO) 
BIT POSITIONS 



Logical Shift Left (LSL). Figure 3-3 shows the effect of an 
LSL instruction. Each bit is shifted to the left. The high-order 
bit (in this case, Bit 31) is shifted into the C and X bits of the 
status register and a is shifted into Bit 0. 

Figure 3-3. Logical Shift Left (LSL) 
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Examples of Logical Shift Left (LSL): 



LSL.L 
LSL 



#3,D0 
D0.D1 



SHIFT LONG WORD IN DO LEFT BY 3 BITS 

SHIFT WORD IN Dl LEFT SHIFT COUNT (IN DO) BIT 

POSITIONS 



Logical Shift Right (LSR). The LSR instruction (Figure 3- 
4) shifts each bit to the right. A is shifted into the high-order 
bit (in this case, Bit 31), and Bit is shifted into the C and X 
bits of the status register. 
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Figure 3-4. Logical Shift Right (LSR) 
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Examples of Logical Shift Right (LSR): 

LSR.L #4,D0 .SHIFT LONG WORD IN DO RIGHT BY 4 BITS 
LSR D0.D1 ;SHIFT WORD IN Dl RIGHT BY SHIFT COUNT (IN DO) 
;BIT POSITIONS 

ROtate Left (ROL). ROL rotates each bit to the left, plac- 
ing the high-order bit of the rotation (in this case, Bit 31) into 
the C bit of the status register and into Bit at the far right 
(see Figure 3-5). 

Figure 3-5. ROtate Left (ROL) 
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Examples of ROtate Left (ROL): 

ROL.L #3,D0 ;ROTATE LONG WORD IN DO LEFT BY 3 BITS 
ROL D0.D1 .ROTATE WORD IN Dl LEFT BY SHIFT COUNT (IN DO) 
;BIT POSITIONS 

ROtate Right (ROR). ROR performs a mirror image of 
ROL. Each bit is rotated to the right. Bit is placed in the C 
bit of the status register and in the high-order bit of the rota- 
tion (in this case, Bit 31). See Figure 3-6. 
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Figure 3-6. ROtate Right (ROR) 
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Examples of ROtate Right (ROR): 



ROR.L 
ROR 



#4,D0 
D0,D1 



ROTATE LONG WORD IN DO RIGHT BY 4 BITS 
ROTATE WORD IN Dl RIGHT BY SHIFT COUNT (IN DO) 
BIT POSITIONS 



Bit Manipulation 

Another group of MC68000 instructions are those that test 
and/or set individual bits. These instructions work on any of 
the 32 bits in a data register, or any of 8 bits of a byte location 
in memory. When using these instructions, you can specify the 
bit in question with either an immediate value or a data 
register. 

The BTST, Bit TeST, instruction tells if any one of a data 
register's 32 bits is set (1) or cleared (0). Alternatively, it can 
test any one of 8 bits of a memory location for the same infor- 
mation. The result of the bit test is deposited in the Z (zero) 
bit in the status register. The BTST instruction can be followed 
by either a BNE, Branch on Not Equal, if the bit is set, or a 
BEQ, Branch on EQual, if the bit is cleared. The MC68000 also 
provides three other bit instructions. These are BSET (Bit SET), 
BCLR (Bit CLeaR), and BCHG (Bit CHanGe). BCHG is nor- 
mally considered a bit toggle because the instruction inverts 
the state of the specified bit, turning it on if it was off, or off if 
it was on. 

Here's a code example: 



LOOP: 







; FIND THE FIRST SET BIT IN Dl 


MOVEQ 


#0,D0 


INITIALIZE THE BIT COUNT 


BTST 


D0,D1 


;CHECK THE NEXT BIT 


BNE 


FOUND 


;FOUND A SET BIT 


ADDQ.W 


#1,D0 


; CHECK THE NEXT BIT 


CMP.W 


#32,D0 




BLT 


LOOP 





u 
u 
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NOTFOUND: 


BSET 


#0,D1 


;NO BIT FOUND 

;SET THE LOW ORDER BIT 


n 


i 






;MORE CODE HERE 


FOUND: 


BCHG 


D0.D1 


;A BIT WAS FOUND 

;TURN OFF THE BIT THAT WAS FOUND 


n 


Branch a 


nd Looi 


9 Instru 


ctions 
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n 
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One important difference between a computer and a simple 
adding machine is the computer's ability to make yes-or-no 
decisions and to change the program flow based on these deci- 
sions. This process is called branching. All computers have this 
feature in some form or another. 

A loop is a series of instructions that must either repeat a 
certain number of times, or repeat until a given condition 
changes. For instance, to print a line of dashes across the 
screen, you would set up a loop to print a hyphen 80 times. 
This loop repeats or iterates a given number of times. 

Another example is when a program waits for input from 
the keyboard; it will probably use a subroutine to check the 
keyboard constantly until a key is pressed, and then continue 
with the program. This loop tests for a change in conditions. 

Branching instructions. The MC68000 microprocessor 
has a group of branch instructions to branch on a variety of 
conditions. A branch must go to a memory location that is 
within ± 32768 bytes from the branch instruction itself. This 
restriction is rarely a problem, but when longer branches are 
required, a JMP (JuMP) instruction provides the programmer 
with the ability to directly branch to any location in memory. 

Branch instructions operate on values stored in the status 
register bits (known as condition code bits) discussed earlier. 
After almost any instruction has completed execution, the 
MC68000 tests the value of the result and sets up the condi- 
tion code register. An MC68000 machine language program 
can then test for condition codes with the Bcc instructions, and 
change the flow of execution elsewhere if the condition has 
been met. 

There are three types of condition code tests. These are 
signed tests, unsigned tests, and miscellaneous tests. Signed 
condition code tests are performed as the result of a signed 
arithmetic operation. Unsigned condition code tests are per- 
formed as the result of unsigned arithmetic operations. Miscel- 
laneous tests are performed when testing for side effects of an 
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operation, such as overflow or carrying (marked by a set over- I 
flow or carry bit of the status register, respectively). 

The following branching conditions are recognized by the 
MC68000: " [_J 

• Signed conditions: 

BEQ Branch EQual i ~i 

BGE Branch Greater or Equal I I 

BGT Branch Greater Than 
BLE Branch Less or Equal 
BLT Branch Less Than 
BNE Branch Not Equal 

• Unsigned conditions: 
BEQ Branch EQual 
BHI Branch High 

BHS Branch High or Same 

BLO Branch LOw 

BLS Branch Low or Same 

• Miscellaneous conditions: 
BCC Branch Carry Clear 
BCS Branch Carry Set 
BMI Branch Minus 

BPL Branch PLus 

BVC Branch oVerflow Clear 

BVS Branch oVerflow Set 

• Unconditional branch: 
BRA BRanch Always 

All of these terms are self-explanatory. BEQ, for instance, 
will cause the program flow to branch if the two given 
operands are equal. 
Some simple branching examples: I j 

THIS EXAMPLE DOES A SIGNED COM- "~" 

PARISON AGAINST THE VALUE 
IN DO, AND BRANCHES IF DO IS GREATER 
THAN 20 

IN BASIC THIS WOULD BE: I j 

IF DO > 20 THEN D2 = 1 

IN C THIS WOULD BE: I I 

if ( DO > 20 ) D2 = 1; 
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SETD2: 



CMP.W 
BGT 


#20,D0 
SETD2 


BRA 


EXIT 


MOVEQ 


#1,D2 



n ; 



EXIT: 



CMP.W 
BLE 



CMP.L 
BLS 



ISHI: 



TST.W 
BEQ 



ADD 
BEQ 



#20,D0 
EXIT 



MOVEQ #1,D2 



A0.A1 
ISLE 



FLAG 

NOTSET 



D0.D1 
ADDTOZERO 



COMPARE DO AND 20 

IF THE OPERATION DO - 20 IS > 

GOTO SETD2 

IF NOT GO TO EXIT 

SETD2 



ANOTHER WW TO DO THE SAME THING 

(AND FASTER) 

IS TO REVERSE THE LOOP TEST: 

COMPARE DO AND 20 

IF THE OPERATION DO - 20 IS <= 

GOTO EXIT 

SETD2 

THIS EXAMPLE DOES AN UNSIGNED 
COMPARISON AGAINST TWO 
ADDRESSES, AND BRANCHES IF THE AD- 
DRESS IN A0 IS <= THE ADDRESS 
INA1 

COMPARE Al WITH A0 
BRANCH IF A0 <= Al 

A0 MUST BE STRICTLY GREATER THAN 

Al 

CHECK TO SEE IF FLAG IS SET OR NOT 



BRANCH IF NOT SET (FLAG=0) 

ADD TWO VALUES AND BRANCH IF THE 
RESULT IS ZERO 



CoMPare (CMP). As shown in the example code above, 
the CMP (CoMPare) instruction is often an essential part of a 
branch. CMP always takes two operands. Source operands can 
be any data value and destination operands can be data or ad- 
dress registers. When the source operand is an immediate 
value, the destination operand can be a memory location. 
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The CMP instruction does not change the source or des- 
tination operands. It subtracts the source operand from the 
destination operand, sets the condition code bits, and throws 
away the result. 

The TeST instruction. The TST (TeST) operation, similar 
to the compare operation, tests the one operand against zero, 
sets the condition codes, and throws away the results. The fol- 
lowing two lines are equivalent: 

TST.W DO 

is the same as 

CMP.W #0,D0 

The DBcc instruction. Another looping construct is the 
DBcc instruction. This instruction provides a looping mecha- 
nism similar to the REPEAT UNTIL looping construct of Pas- 
cal. The DBcc instruction repeats a loop UNTIL either the 
condition becomes true, or the loop counter goes below (as- 
suming the loop counter was initially set to a positive value). 

The format of the DBcc instruction is DBcc Dn,LABEL. 
The cc may be any of the following condition codes. 

• Signed conditions: 

DBEQ Decrement and Branch EQual 
DBGE Decrement and Branch Greater or Equal 
DBGT Decrement and Branch Greater Than 
DBLE Decrement and Branch Less or Equal 
DBLT Decrement and Branch Less Than 
DBNE Decrement and Branch Not Equal 

• Unsigned conditions: 

DBHI Decrement and Branch High 

DBHS Decrement and Branch High or Same 

DBLO Decrement and Branch LOw ' — ' 

DBLS Decrement and Branch Low or Same 

• Miscellaneous conditions: I 
DBCC Decrement and Branch Carry Clear { — J 
DBCS Decrement and Branch Carry Set 

DBMI Decrement and Branch Minus j ! 

DBPL Decrement and Branch PLus ' — 
DBVC Decrement and Branch oVerflow Clear 

DBVS Decrement and Branch oVerflow Set I I 

U 
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• Special conditions: 
DBF Decrement and Branch False (conditional test is never 
true) 

DBT Decrement and Branch True (conditional test is always 
true) 

The DBcc instruction works in the following manner: If 
the specified condition is true, the loop terminates and execu- 
tion continues with the next instruction; if it is false, the lower 
16 bits of the specified register are decremented by one. If the 
result is — 1, the loop terminates and execution continues with 
the next instruction. If the result is not — 1, the program 
branches back to the top of the loop. 

The DBcc instruction only uses the bottom 16 bits of the 
destination data register for a loop counter. The effect is that 
loop counters cannot be larger than 32,767. Larger loop counts 
can be accomplished, however, simply by using nested loops. 

The MC68010 processor has a special loop mode for DBcc 
instructions with a relative offset of —4 (see the example be- 
low). The MC68010 has a two word prefetch queue in addi- 
tion to a one word instruction decode register. In a DBcc loop 
with a displacement of —4, the DBcc instruction and its 
branch displacement are held in the prefetch queue, and all 
opcode fetches are suppressed and only operand reads and 
writes are performed until an exit condition is met. This means 
that any single- word MC68010 instruction used inside the 
loop will run faster because the MC68010 doesn't refetch the 
loop and DBcc instructions with each loop. It holds them and 
reuses them without reading them in from memory over and 
over again. 

Some of the more important cases include fast block 
moves such as: 



LEA.L SOURCEADDRESS.A0 

LEA.L DESTINATI0NADDRESS.A1 

MOVE.W #LENGTHOFMOVE,D0 

LOOP: 

MOVE.B (A0)+,(A1) + 

DBEQ D0.LOOP 



GET THE SOURCE 

ADDRESS 

GET THE DESTINATION 

ADDRESS 

LOAD THE NUMBER OF 

LOOPS 

MOVE 1 BYTE IN THE 

LOOP 

NOTE DISPLACEMENT OF 

-4 
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The bits tested in condition codes for a Bcc or DBcc have 
not been discussed in this section. For beginning assembly 
programmers, it's not critical. For a reference on the bits tested 
for each of the different condition codes, see the Bcc instruc- 
tion in the Appendix at the back of this book, or see a 
MC68000 reference manual. 

Subroutine Calls and Returns 

There are two instructions for calling subroutines: BSR (Branch 
to SubRoutine) and JSR um P to SubRoutine). The BSR is 
used when you're absolutely certain that the beginning of the 
subroutine is within 32,768 bytes of the BSR instruction. This 
instruction has the same constraints as the Bcc instructions. 

The JSR instruction is more flexible. It can jump to a sub- 
routine anywhere in memory. 

These instructions allow the program to temporarily 
branch to another place in the program, and later return to the 
instruction following the BSR or JSR. This is accomplished by 
saving the return address on the stack. The return address is 
the program counter (PC) address at the time the BSR or JSR 
is executed. Later, when an RTS (ReTurn from Subroutine) in- 
struction is executed, the old PC address is removed from the 
stack and reloaded into the PC. This forces the program to be- 
gin executing code where it left off when it encountered the 
JSR or BSR. 

The following example pushes two long words on the 
stack and calls a subroutine. The subroutine adds the two val- 
ues and returns the result in register DO. 



MOVE.L VALUE1,-(SP) 
MOVE.L VALUE2,-(SP) 



JSR ADDSUBR 

ADDQ.L #8,SP 



SUBROUTINE CALL SETUP 

PUSH THE FIRST ARG ON THE 

STACK 

PUSH THE SECOND ARG ON 

THE 

STACK 

CALL THE ADDSUBR 

REMOVE VALUE 1 AND VALUE2 

. MORE CODE HERE 

THE ADDSUBR SUBROUTINE- 
ADD TWO STACK ELEMENTS 



u 
u 
u 
u 
u 
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AND 
RETURN 

A VALUE IN REGISTER DO 
ADDSUBR: 

MOVE.L 4(SP),D0 
ADD.L 8(SP),D0 

RTS ; ALL SUBROUTINES END WITH 

;RTS 



Sign Extension 

It is often necessary to increase or decrease the size of data. 
Decreasing the size is easy. If the data was a 16-bit word 
value, and has now become an 8-bit byte value, simply start 
accessing the data with byte addresses. Don't forget to update 
the address pointer when converting down to a smaller size, 
especially if the data is not in a register. To increase, or sign 
extend, the value of a piece of data, use the EXT (EXTend sign 
bit) instructions. Sign extension is the process of propagating 
the sign bit (MSB) of a data value to the upper part of a word 
or long word. 

Consider the following problem. A program needs to add 
together two numbers. These numbers (for this example) are 
—5 and — 1. The obvious answer to this is: 

In decimal In 32-bit binary arithmetic 

+ -1 + FFFFFFFF 

-6 FFFFFFFA 

As long as all the operators are long words, you will re- 
ceive the correct result, but consider for a moment what hap- 
pens when —5 is a word and —1 is a long word. If your 
arithmetic doesn't use sign extension, the upper bits of the —5 
are filled with zeros and the result is not —6: 

In 32-bit arithmetic without sign extension: 
0000FFFB (—5 as a word with no sign extension) 
+ FFFFFFFF (-1 as a long word) 

10000FFFA (not -6) 

Without sign extension of small values, incorrect results 
may occur. The MC68000 microprocessor provides two in- 
structions to sign extend values. The instruction EXT.W forms 
a 16-bit word from a byte by extending its sign bit (bit 7) 

43 



Chapter 3 



U 
U 



through bits 8-15 of a data register word. If the EXT.L instruc- j 

tion is used to change a 16-bit value to a 32-bit value, bit 15 ^ 
of the 16-bit word is extended through bits 16-31 of a data 

register. I I 

The following example loads a byte variable and sign ex- ' — 

tends it's value to a full 32 bits. __. . 

MOVE.B VAR.D0 I J 

EXT.W DO ;CONVERT BYTE TO WORD 

EXT.L DO .CONVERT WORD TO LONG WORD 

There are a variety of instructions not covered in detail 
here, but these are among the most common and most power- 
ful instructions available on the MC68000 microprocessor. You 
will want to learn others. Please refer to a MC68000 
microprocessor manual or the Appendix at the end of this 
book for more information about other instructions. 

You should also note that this book does not cover the 
MC68000 supervisor mode. If you're interested in system-level 
programming on the MC68000 and the instructions available 
when a program executes in supervisor mode, study the Ap- 
pendix or an MC68000 microprocessor manual. 
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Addressing Modes 

An address is a number or symbol that stands for a memory 
location. When a microprocessor performs an instruction, the 
instruction must first be loaded from memory. The same is 
true of loading or storing data. To load instructions or data 
from memory, the microprocessor uses the address of its mem- 
ory locations. Each memory location has a numerical address. 
In programs, the numerical addresses can be given symbolic 
names for convenience. 

When the MC68000 reads from or writes to a memory lo- 
cation, it uses a 32-bit number as an address. The micro- 
processor can calculate the address to be used by combining a 
variety of numbers. In some cases it may add together two 
registers to form an address. In other cases it may add a con- 
stant value to a register to form an address. In yet other cases, 
the address of a piece of data is simply the number presently 
held in one of the address registers. 

The method used to combine numbers and registers to 
form an address is called an addressing mode. Each instruction 
dictates an addressing mode used for that instruction. If the 
instruction manipulates data in a register, the addressing mode 
is called register direct. If the same instruction manipulates 
data at a memory location pointed to by an address register, 
the addressing mode is called address register indirect. The 
MC68000 microprocessor has 11 different addressing modes. 
Some are obvious and simple; others are complex and require 
study. 

As mentioned before, all machine language can be gener- 
ally divided into two parts: the opcode (the instruction given to 
the machine) and the operand (the memory location affected 
by the instruction). If the data immediately follows the 
opcode, the microprocessor doesn't have to look somewhere 
else in memory for it. This is called immediate addressing. 

As you might suspect, other forms of addressing are more 
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complex. The microprocessor can look for operands at a sped- j I 

fied address. If you were to think of the microprocessor's oper- 
ation as if it were a post office, this would be analogous to 
delivering mail based on the address on the envelope. This is i j 

called absolute addressing. 

Sometimes people move and leave forwarding addresses - - ( 

with the postmaster. When running across a letter written to j | 

such people, the mail carrier has to go to a central file and """^ 

look up the new address. This situation is very similar to regis- 
ter direct addressing. You store the address of the operand in a 
data or address register, and tell the microprocessor to look 
there for the address. 

When the mail carrier goes to the address on the envelope 
and discovers that it's a trailer court or an apartment complex, 
he or she has to have a little more information, such as lot or 
apartment number, to find the right address. This is analogous 
to register indirect with displacement addressing. 

In all, the Amiga's MC68000 and MC68010 micro- 
processors have 1 1 basic addressing modes. MC68000 ma- 
chine language programs can also directly access other 
registers not covered here. The 11 addressing modes discussed 
here are: 

Name Format 

Inherent 

Register Direct Rn 

Address Register Indirect (An) 

Address Register Indirect with Postincrement (An)+ 

Address Register Indirect with Predecrement — (An) 

Address Register Indirect with Displacement dl6(An) 

Address Register Indirect with Index and Displacement d8(An,Rn) 

Absolute value | | 

Program Counter Relative with Displacement dl6(PC) l - — ' 

Program Counter Relative with Index and Displacement d8(PC,Rn) 

Immediate Value #value I 1 

The following is a summary of the 11 different addressing 
modes and some of their possible uses. The major heads con- 
tain the technical name of the addressing mode and the format j 
for its use. Dn, for instance, refers to any data register. The ad- 
dressing modes with indexes start with dl6 or d8, which indi- 
cates that an 8- or a 16-bit index is the first element of the [ j 
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format. Rn refers to any data or address register. The + and 
— signs refer to increment and decrement. If the + or — 
sign leads the addressing mode format, it is an indication that 
the increment or decrement occurs before the address is 
accessed. A trailing + or — sign indicates that the incre- 
ment or decrement occurs after the address is accessed. 

Inherent 

Inherent addressing is the easiest of all — the microprocessor 
knows from the opcode alone which addresses to use. For ex- 
ample, an RTS instruction has no operand field, yet the 
microprocessor knows to fetch the return address from the 
stack. Two instructions that require no operands are NOP (No 
OPeration) and RESET. 

Register Direct Rn 

In the register direct addressing mode, the operand is in the 
specified address, or data register. Most instructions use either 
a data register or an address register as one of the operands. 
Registers are most commonly intermediate values or heavily- 
used variables in a section of code. 

Address Register Indirect (An) 

In the address register indirect addressing mode, the address 
of the operand is in the specified address register. This 32-bit 
value is used to fetch the operand for calculation. On the 
MC68000 and MC68010, only the lowest 24 (out of a possible 
32) bits of the address are used. On the MC68008, only the 
bottom 20 bits are used. The programmer, however, should 
not use the upper 8 bits of address for flag bits or nonaddress 
data. This trick was used in some early MC68000 programs — 
much to their detriment when they were ported to the 
MC68020, a microprocessor that uses all 32 address bits. 

The address register indirect mode is commonly used just 
after an address has been calculated, or when the same ad- 
dress is used repeatedly. For example, the following code uses 
the same address multiple times in a loop, but only calculates 
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LAB: 

MOVE.W (AO),DO ; LOAD A COMMON VARIABLE THAT 



If the assembly program has created an upward-growing 
stack, then a stack push operation may be performed in the 
following way. (Although stacks normally grow downward on 
the Amiga, it is not necessary that the programmer use stacks 
in this manner.) 



U 
(J 



it once. After it's calculated, it's placed in address register AO: |^J 
LEA USEDALOT.A0 

U 

; GETS TRASHED 

DO SOME WORK [_] 

BRA LAB 

This addressing mode does not modify the specified ad- 
dress register. 

Address Register Indirect with 
Postincrement (An)+ 

Address register indirect with postincrement is similar to ad- 
dress register indirect, but as the name implies, the value in 
the address register is automatically increased after each use. If 
you use this addressing mode with a long-word instruction 
(like MOVE.L), the address register will be incremented by 
four. If you use it with a word instruction (like MOVE.W), it 
will be incremented by two. And if you use it with a byte in- 
struction (like MOVE.B), it will be incremented by one. This 
addressing mode provides an easy means of processing arrays, 
stacks, queues, and other data structures. 

If the address register is the stack pointer (SP or A7) and 
the operand size is a byte, then the stack pointer is automati- 
cally incremented by two instead of one. This keeps the stack 
properly aligned at all times. 

If the assembly program uses a downward-growing stack, 
automatically available with the SP register, a stack pop oper- | j 
ation is readily available. ^— ' 

; STACK POP (STACK GROWING DOWNWARD) , - 

MOVE.L (SP)+,D0 ; TAKE THE TOP ELEMENT OFF THE STACK AND i ! 

; SWE IT IN DO ^ 
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MOVE.L D0,(A3)+ 



STACK PUSH (STACK GROWING UPWARD) (AS- 
SUMING A3 IS STACK POINTER) 
PUSH DO TO THE TOP OF STACK FOR FUTURE 
USE 



Some more examples: 



MOVE.W D1,(A3)+ 

MOVE.W (A2)+,D1 
MOVE.L (A0)+,(A1)+ 



QUEUE SATE/RETRIEVE (ASSUME A2 IS HEAD 

OF 

QUEUE, A3 IS TAIL OF QUEUE) 

CHECK QUEUE LIMITS 

S/e/E ITEM 

CHECK QUEUE LIMITS 

GET ITEM 

MOVE LONG WORD POINTED TO BY AO TO 

LONG WORD POINTED TO BY Al, THEN 

INCREMENT 

BOTH AO AND Al BY 4 AFTER THE 

INSTRUCTION. 

THIS IS VERY USEFUL FOR COPYING LARGE 

CHUNKS OF DATA IN A LOOP 



Address Register Indirect with 
Predecrement ~"(An) 

Using address register indirect with predecrement causes the 
address of the operand contained in the address register to be 
decremented by one, two, or four, depending upon the size of 
the operand specified, before the operation takes place. The ad- 
dress in the specified address register is used to fetch the oper- 
and or store data. If the address register is the stack pointer 
(SP or A7), and the operand size is a byte, the stack pointer is 
automatically decremented by two instead of one. This keeps 
the stack properly aligned at all times. 

Register indirect with predecrement mode has many uses. 
These include, among other things, array, stack, and queue 
manipulation. 

If the assembly program uses a downward-growing stack, 
automatically available with the SP register, a stack push oper- 
ation is readily available. 



MOVE.L D0,-(SP) 



STACK PUSH (STACK GROWING DOWNWARD) 
; PUSH DO TO THE TOP OF STACK FOR FUTURE 
;USE 
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If the assembly program has created an upward-growing 
stack, then a stack pop operation may be performed in the fol- 
lowing manner: 

STACK POP (STACK GROWING UPWARD) (AS- 
SUMING A3 IS STACK POINTER) 
TAKE THE TOP ELEMENT OFF THE STACK AND 
S/B/E IT IN DO FOR LATER USE 



MOVE.L -(SP),D0 



Some more examples: 



MOVE.W 

MOVE.W 
MOVE.W 



D1,-(A3) 

"(A2),D1 
-(AO)-(Al) 



QUEUE SAVE/RETRIEVE (ASSUME A2 IS 

HEAD OF QUEUE, A3 IS TAIL OF QUEUE) 

CHECK QUEUE LIMITS 

SAVE ITEM 

CHECK QUEUE LIMITS 

GET ITEM 



DECREMENT BOTH AO AND Al BY 2, 
THEN MOVE THE WORD POINTED TO BY AO 
TO 

THE WORD POINTED TO BY Al. THIS IS 
VERY 

USEFUL FOR COPYING LARGE CHUNKS OF 
DATA ; 
; IN A LOOP 

Remember that the amount of increment or decrement de- 
pends on the size specifier on the actual instruction. 

Address Register Indirect with 
Displacement dl6(An) 

Address register indirect with offset uses the address contained 
in the specified address register added to a 16-bit displacement 
value as the address of the operand to be fetched or stored. 
The address register is not modified by this addressing mode. 
This addressing mode has many uses. The most common 
use is accessing stack variables that exist as constant locations. 
Consider the following example: 



MOVE.L 
MOVE.B 
MOVE.W 



JSR SUBROUTINE 



VAR3,-(SP) 
VAR2,-(SP) 
VARl.-(SP) 



S/R/E THIRD VARIABLE 
SWE SECOND VARIABLE 
SWE FIRST VARIABLE 



The stack now looks like Figure 4-1. 
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Figure 4-1. Stack after loading variables. 





Even 
Byte 


Odd 
Byte 




sp*ie 


Uariable nunber three 
high word 


SP+11 


SP+8 


Variable nunber three 
low word 


SP+9 


SP+6 


00688800 


Variable 
nunber two 


SP+7 


SP*4 


Uariable nunber one 


SP*5 


SP+2 


Return progran 
Counter high word 


SP+3 


SP+8 


Return progran 
Counter low word 


8P*1 



TO RETURN VARIABLES FROM STACK 



JSR 


SUBROUTINE 




M0VE.W 


4(SP),D0 


TO ACCESS VARIABLE 1 


ADD.B 


7(SP),D0 


TO ACCESS VARIABLE 2 


M0VE.L 


8(SP),A0 


TO ACCESS VARIABLE 3 


M0VE.L 


DO,(AO) 


(VARIABLE 3) = VARIABLE 1 + VARIABLE 
2 

ANOTHER WW TO RETURN VARIABLES 


JSR 


SUBROUTINE 


SAME AS ABOVE 


TST.W 


(SP)+ 


POP VARIABLE 1 


TST.B 


(SP)+ 


POP VARIABLE 2 


TST.L 


(SP)+ 


POP VARIABLE 3 

MORE EFFICIENT WW TO RETURN 
VARIABLES 


JSR 


SUBROUTINE 


SAME AS ABOVE 


ADDQ.L 


#8,SP 


POP ALL 3 VARIABLES SIMULTANEOUSLY 



Address Register Indirect with Index and 
Displacement d8(A/i,R#i) 

In this addressing mode, the eight-bit displacement, the speci- 
fied address register, and the specified index register are added 
together to generate the address of the operand. This calcu- 
lated value is used to fetch or store the data used by the 
instruction. 

The second register, commonly known as the index regis- 
ter, is either a data register or an address register. This register 
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is referenced as a 16-bit or a 32-bit value. By default, the reg- 
ister acts as a 16-bit value. To specify the size of this register, 
append to the opcode either .L for a 32-bit value, or .W for a 
16-bit value. 

This addressing mode is very useful for array indexing. 
Consider an array of data structures, in which each structure is 
16 words long. The following code fragment totals the second 
words of the array (see Figure 4-2). 



LOOP: 



LEA.L 


ARRW_OF_STRUCTS,A0 




MOVE.L 


NUM_0F_STRUCTS,D1 




LSL.L 


#4,D1 


GET MAXIMUM INDEX 
(NUM*16) 


MOVEQ 


#0,D0 


INIT INDEX 


MOVEQ 


#0,D2 


SUM 


ADD.W 


2(A0,D0),D2 


SUM = SUM + 
NEXT-ELEMENT 


ADD.W 


#16,D0 


INDEX = INDEX + 
STRUCT_SIZE 


CMP.W 


D1.D0 


IS DO - Dl < 0? 


BLT 


LOOP 

(the rest of the code) 


; YES, DO NEXT ITERATION 



Figure 4-2. The effect of address register indirect with index and 
displacement. 
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Another example is a quick multiply by two in an address 
register: 

LEA.L 0(A0,A0.L),A0 ;MULTIPLY AO BY 2 

Absolute Addressing value 

The absolute addressing mode has two variations — absolute 
short and absolute long. With absolute short mode, the lower 
half of the effective address follows the opcode in memory as 
a word value. The specified word value is sign extended and 
then used as the address of the operand in question. 

The absolute short addressing mode can only access the 
lowest or highest 32K memory locations. This mode provides 
a short, quick way to use programs or temporary storage. It is 
short and quick because it saves a word of memory and a read 
cycle. 

The following example loads the TRAPV vector, and 
probably would only be executed in supervisor mode. 

LEA.L MY_TRAPV_ROUTINE,A0 ; GET A SUBROUTINE ADDRESS 
MOVE.L A0,$001C.W ; SWE IT IN TRAPV VECTOR 

With absolute long addressing, the effective address occu- 
pies two words of memory immediately after the opcode. This 
addressing mode gives the user access to any memory loca- 
tion. The labels used are commonly called global variables. For 
example, if you assigned the label DATALOC to a memory lo- 
cation, you could store information in that location with the 
following line of code (which transfers a word of information 
from data register D7 to the memory location DATALOC): 

M0VE.W D7.DATAIOC ;SWE SOME DATA 

An Amiga machine language program should always use 
labels when referring to any type of absolute data. This allows 
the assembler to generate the correct relocation information. 
Without relocation information, the machine language pro- 
gram cannot execute correctly in the multiprocessing environ- 
ment of the Amiga. 

A multitasking environment must be able to move pro- 
grams around in memory. If you assign absolute constants 
(such as telling the program to jump to a specific address) 
without relocation information, your program will crash when- 
ever it is moved to a different location in memory. All the ab- 
solute addresses will be wrong. 
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MOVE.W 


INDEX.DO 


; GET JUMP TAB] 


LSL.L 


#2,D0 


; MULTIPLY BY 2 


JMP 


2(PC,D0) 


; CALL SUBROUT 


BRA 


EXIT 




DC.L 


SUBROUTINEO 


; INDEX 


DC.L 


SUBROUTINE1 


; INDEX 1 


DC.L 


SUBROUTINE2 


; INDEX 2 


EXIT: 
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Program Counter Relative with 
Displacement dl6(PC) 

With this addressing mode, the 16-bit displacement value is 
added to the program counter and used as the address of the I j 

operand fetched or stored. The program counter is unmodified ' — ' 
by this addressing mode. 

This has three important uses: j I 

• When the source code makes reference to a label, and the 
referenced label is within 32,768 bytes of the current location 
counter, as in the statement JMP LABEL 

• For constant jumps through a jump table 

• To find the address of the current instruction as in the fol- 
lowing statement: LEA.L -4(PC),A0 

Program Counter Relative with Index and 
Displacement d8(PC,Rn) 

In program counter relative with index and displacement ad- 
dressing, the eight-bit displacement, the program counter, and 
the specified secondary register are added together to generate 
the address of the operand. This calculated value is used to 
fetch or store the data used by the instruction. 

Either a data or address register can play the role of the 
secondary register, commonly known as the index register. 
This register may act as a 16- or 32-bit value. By default, the 
register will be accessed as a 16-bit value. To specify the size 
of this register, append to the opcode either .L (as in LEA.L) 
for a 32-bit value, or .W (as in LEA.W) for a 16-bit value. 

This addressing mode is most useful when doing a vari- 
able jump through a jump table as in this example: 

YDEX i | 

IN TABLE 

U 

u 
u 

Li 



n 



n 



n 
n 
n 



Amiga Machine Language Programming 



Immediate #value 

The specified value is used as the source operand for the 
instruction. 

This addressing mode is used to load a constant value. 
Every time this addressing mode is used, there is one less con- 
stant to store in data space. The data follows immediately after 
the opcode. The data can be a byte, a word, or long word. 

The MC68000 has a special immediate mode for small 
operands. In this mode, the data is actually contained within 
the opcode itself. This quick mode can move a number in the 
range —128 to +128 to a register or memory location, or add 
or subtract numbers from 1 to 8. 

The following is an example of immediate addressing 
mode. 



AND.L #$7F,D0 
OR.W #$8000,D0 

BMI CONTINUE 
NOP 
CONTINUE: 

(rest of program here) 



MASK OUT UPPER 25 BITS 

TURN ON SIGN BIT (WORD SIZED 

VALUE) 

BRANCH IF MINUS 

THIS IS NEVER EXECUTED 



Differences between the MC68000 and the 
MC68010 

There are four important differences between the MC68000 
and the MC68010. One of the most important changes is the 
MC68010 microprocessor's ability to continue an instruction 
correctly after a bus error has occurred. Because of the orga- 
nization of the instruction prefetch queue, this is not always 
possible on the MC68000 microprocessor. The difference be- 
tween the two chips in this area is the manner in which the 
MC68010 writes out its bus error stack frame. Enough infor- 
mation is saved so the MC68010 can continue the instruction 
when the processor returns from bus error exception processing. 

Another difference between the MC68000 and the 
MC68010 microprocessors is that the MOVE to Status Register 
instruction can only be executed in supervisor mode on the 
MC68010. 
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One of the most noticeable modifications in the MC68010 
microprocessor is the speedup of the multiply and divide in- 
structions. The MC68010 multiplies and divides 16-bit num- 
bers approximately 50 percent faster than the MC68000. 

The last difference between the MC68000 and the 
MC68010 is the DBcc LOOP MODE, described previously (un- 
der the heading "DBcc Instructions" in Chapter 3). This modi- ] j 
fication provides for fast execution of tight two-instruction 
loops. Two extra bus cycles are saved for each iteration of the 
loop, providing a substantial speed improvement. The key to 
this MC68010 feature is that the instruction within the inner 
loop of the DBcc must be exactly one word, or two bytes long. 
When the MC68010 detects this situation, it terminates in- 
struction fetching and simply executes the prefetched instruc- 
tions until the loop completes. When DBcc instructions appear 
frequently, a MC68010 microprocessor can increase the speed 
of programs by as much as 15 percent. 

16-bit Programming Considerations 

Users of the MC68000 and MC68010 consider this set of pro- 
cessors to be 16- /32-bit machines. This term comes from the 
fact that although these microprocessors have many 32-bit op- 
erations, they were designed as 16-bit machines. The most no- 
table evidence for this is the lack of 32-bit X 32-bit multiply 
and divide instructions, the fact that 32-bit instructions actu- 
ally operate more slowly than their 16-bit counterparts, and 
the fact that the data path for these computers is physically 16 
bits wide. On a true 32-bit machine, these three deficiencies 
would not exist. 

With this information in mind, however, the MC68000 I I 

programmer can make better decisions about optimizing code. — 

One of the best choices to make when coding for the MC68000 
microprocessors is to use 16-bit data values wherever possible. I j 
In many instances, 16 bits are sufficient. "■ — 

Thoughtful planning is the key when writing source code. 
In some instances, such as large data moves, 32-bit operations I j 
might seem superior. Since the physical data path is only 16 ^ — ' 

bits wide, all 32 operations take at least two extra cycles to ex- 
ecute. By using 32-bit counters throughout a program, the j 
speed of execution may be degraded considerably. *- — ' 

Since the 32-bit X 32-bit multiplies and divides must be 
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simulated, a 16-bit multiply or divide is always superior in 
terms of speed. It takes at least three 16-bit multiplies to simu- 
late a 32-bit X 32-bit multiply. 

Another situation concerns large arrays. One addressing 
mode common on 32-bit machines is register indirect with 32- 
bit displacement. This is useful when accessing arrays, because 
the displacement can be the starting address of the array and 
the register can contain the index. Since this addressing mode 
does not exist on the MC68000 or MC68010 microprocessors, 
the register indirect with index and displacement addressing 
mode must be used. The machine language programmer per- 
forming array indexing must keep reloading the base offset of 
the array. The alternative is to cache the base offset in an ad- 
dress register. Keep this in mind for good array indexing 
performance. 

The MC68000 and MC68010 microprocessors do not have 
barrel shifters. A barrel shifter is a piece of hardware that 
speeds up shifts and multiply instructions. Since the MC68000 
doesn't have a barrel shifter, a shift of three bits takes longer 
than a shift of two bits. The longer the shift, the more time it 
takes. On more complex microprocessors, like the MC68020, 
all shift instructions take the same amount of time. 

Beware of MOVEM instructions for small numbers of reg- 
isters. The MOVEM instruction is very fast when loading or 
storing large numbers of registers. Like any complex instruc- 
tion, it has a setup time. Whenever moving only one or two 
registers, it's faster to use one or two move instructions. If 
three or more registers are moved at one time, it's faster to use 
a single MOVEM instruction. 

Although the MC68000 microprocessor has the CLR in- 
structions to clear data registers, the MOVEQ #0,Dn is faster 
and always clears all 32-bits. 

It is wise to use some registers as temporaries and others 
to hold register variables. On the Amiga, it is conventional to 
use the registers DO, Dl, AO, and Al as temporary registers, 
and the other registers as variables. Most Amiga ROM kernel 
subroutines don't preserve the contents of DO, Dl, AO, and 
Al. They are treated as scratch registers. If you write subrou- 
tines that behave the same way, you'll have consistent per- 
formance, and other Amiga programmers will more easily 
understand them. 
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II The Amiga CLI 

(Command Line Interface) 



In order to use the programs and programming methods pre- 
sented in the rest of this book, you'll need to use a small 
group of Amiga CLI commands. The following short presenta- 
tion is intended as a refresher, not a substitute for the 
AmigaDOS Manual (Bantam Books), nor is it a complete discus- 
sion of even these few commands. If you're totally unfamiliar 
with the Amiga CLI, it's a good idea to put this book down 
and study and practice with the CLI until you're satisfied that 
you understand the CLI and its commands. The Amiga system 
documentation (which accompanies each Amiga) gives much 
more detail than is presented here, and the AmigaDOS Manual 
provides a complete reference on all CLI commands. 

Getting to the CLI 

There is a special command file that gets executed every time 
you boot your Amiga from your Workbench disk. This com- 
mand file, which is a series of AmigaDOS commands, can be 
found in the S directory of your Workbench disk, with the 
name STARTUP-SEQUENCE. Its job is to get the Amiga 
started and bring in the Workbench system, and then clear the 
screen and quit. 

While the startup sequence is being executed, you can see 
the CLI window (also known simply as the CLI) in action, 
executing commands. The last command in the standard start- 
up sequence file is an ENDCLI, which eliminates the CLI win- 
dow. If this last command is deleted from the startup sequence 
command file, the CLI window will remain visible and usable 
after the startup process is finished. 

You can make a copy of your Workbench disk using the 
Workbench duplicate menu option, and edit the startup se- 
quence found in the S directory with a text editor. Remove the 
ENDCLI instruction to maintain your CLI window on the 
screen. 
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The other way to get access to a CLI window is to use the 
Preferences program on the Workbench disk: 

• Start the Amiga using the Kickstart and Workbench disks. 

• Double-click on the Workbench disk icon. | j 

• Double-click on the Preferences icon within the Workbench *~~ ' 
disk window. 

• When the Preferences screen appears, locate the CLI on/off j j 
gadget and use the mouse to click once on the ON side of *" 
the gadget. 

• Use the Save gadget (click it once) to save the new prefer- 
ences to disk. 

• Reboot the Amiga (press CTRL and both the left and right 
Amiga keys simultaneously). The Amiga keys are the keys to 
the right and left of the space bar. (The left Amiga key has 
been changed to a Commodore key on the Amigas 500 and 
2000). 

This will cause the Amiga to perform the startup-sequence 
again and the new Preferences will take effect when the Work- 
bench screen appears. 

Now you can open a CLI window by following these 
steps: 

• Double-click on the Workbench disk icon. 

• Double-click on the System Drawer icon in the Workbench 
disk window. 

• You'll see an icon for CLI in the System Drawer window. 

• Double-click on the CLI icon. 

• Click on the close window gadgets for the Workbench disk 
window and the System Drawer window. 

• You should be left with a CLI window which can be resized 
to your convenience, but with no close gadget. 

The CLI window is an Amiga programmer /user interface 
which operates like most traditional computers that have no 
mouse, windows, or drop-down menus. This window permits 
you to type in commands to the Amiga and have the Amiga 
perform them. The Workbench disk contains a directory 
named C, which contains many useful commands. Some of 
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COPY Copy files 

DELETE Delete files 

RENAME Rename files 

MAKEDIR Make a directory 

LIST List contents of directory 

NEWCLI Start a CLI 

ENDCLI Quit a CLI 

ASSIGN Give a directory or device a logical name 

EXECUTE Execute a file of CLI commands 

RUN Execute a CLI command or a program as a background- 
process 

CD Current directory 

The short list of commands above is intended to get you 
started. If you are a beginner, it would be well worth your 
time to practice the commands. 

It's necessary to have the Workbench disk inserted in a 
disk drive (DFO:, also known as drive 0) in order for the Amiga 
to be able to find the commands when you type them in. The 
Amiga knows to look in the C directory on the boot disk for 
the command's program code. The program code is then 
loaded in from disk and executed by the Amiga. 

The COPY Command 

The COPY command is used to copy a file. You must specify a 
source name (from) and a destination name (to). Recall that a 
file name can be preceded by a directory specification. The fol- 
lowing examples show a few of the many ways to use the 
COPY command to move files around. 

COPY DFO:S/STARTUP-SEQUENCE TO DF1: Copies the file 
STARTUP-SEQUENCE from the S directory of the disk in DFO: 
to the main (root) directory of the disk in DF1: (the external disk 
drive, which is also known as drive 1). 

COPY DFO:S/STARTUP-SEQUENCE TO RAM:TEMPORARY_ 
STARTUP Copies the STARTUP-SEQUENCE file from the S di- 
rectory of the disk in drive to the ramdisk, and simultaneously 
gives it the name TEMPORARY-STARTUP. 

COPY RAM:SOURCE_FILE TO DFl:SOURCES/ Copies a file 

named SOURCE—FILE from the ramdisk to the sources directory 
on the external disk drive. Notice that in order to do this COPY 
you don't have to type the name of the file a second time. The 
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Amiga will simply assume the name of the file is unchanged. 
This is identical to the following command (which requires a lit- 
tle more typing): COPY ram:source_file to DFl:sources/ 
source— file. 

COPY is one of the Amiga's most useful commands and 
is very frequently used. 

The DELETE Command 

The DELETE command is used to eliminate a file completely. 
The DELETE command uses only a single filename, which can 
be prefixed with a directory specification. 

DELETE DFl:SOURCES/UNNEEDED_FILE Deletes the file 

named UNNEEDED-FILE from the SOURCES directory on the 
disk in drive 1. 

DELETE RAM:INCLUDES/SYSEQUATES.ASM Deletes the file 
SYSEQUATES.ASM from the INCLUDES directory in the 
ramdisk. 

DELETE RAM:INCLUDES ALL Will delete all the files in the IN- 
CLUDES directory in the ramdisk. The directory itself (named 
INCLUDES in this example) will also be deleted. 

DELETE DFl:SOURCES/#?.ASM Will delete all the files in the 
SOURCES directory, on the disk in drive 1, that end with the 
extension ASM (any characters separated from the main file- 
name by a period are referred to as an extension). This is a quick 
way to delete multiple files that all have the same extension and 
that are in the same directory. This wildcard-matching technique 
for identifying multiple files is described more thoroughly in the 
AmigaDOS Manual. You can sometimes use it with other 
commands. 

The DELETE command must be used cautiously. Once a 
program is deleted from an Amiga device (disk or ram- 
disk) it is irretrievable. Never use the DELETE command 
unless you're sure the file is really not needed, or you 
have a backup of the file. 
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The RENAME Command 

RENAME is used to change the name of a file. It's very useful I j 

for manipulating the names of files to conform with your per- '- — ' 
sonal taste and style. The following simple example is typical: 

RENAME DFl:TOOLS/MICROEMACS TO DFl:TOOLS/EMACS | | 

Changes the name of the MICROEMACS program in the tools 
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directory on DF1: to EMACS (using a shorter name for a file can 
minimize typing of repetitive commands). 

RENAME DFO:C/EXECUTE TO DF0:C/DO Changes the name of 
the Amiga's EXECUTE command (which lives in the C directory 
of the Workbench disk) to DO. Whenever you need to use the 
EXECUTE command, you have to type in DO instead. 

RENAME RAM:SOURCE AS RAM:NEWSOURCE Uses RENAME 
to change the name of a file in the ramdisk. 

RENAME DFO:STARTUP-SEQUENCE DFO:S/STARTUP- 

SEQUENCE This RENAME is a. bit sneaky. It changes the path- 
name of the file and, consequently, moves the file from the root 
directory of the disk in drive DFO: to the S directory on the 
same disk. 



The MAKEDIR Command 

MAKEDIR allows you to create a new directory on a disk or in 
another existing directory. Sometimes it's convenient to COPY 
a group of related files to a single directory. For example, the 
companion disk has a directory called SOURCES, which con- 
tains all the source code program files for this book. If you're 
working on many source files at the same time, you might 
wish to follow the first example in this list: 

MAKEDIR RAM:MYSOURCES 

COPY FROMWHEREVER:SOURCEFILE TO RAM:MYSOURCES/ 
SOURCEFILE This makes a directory within the ramdisk named 
MYSOURCES, and copies the SOURCEFILE from 
FROMWHEREVER to the new directory MYSOURCES in the 
ramdisk. 

Remember that any disk or ramdisk can have directories, 
and directories can have subdirectories. There's always a root 
directory for DFO:, DF1:, and RAM:. It's always the first di- 
rectory accessed. Any additional directories in that device 
will be descendants or children (subdirectories) of the root. 
Those subdirectories can also have subdirectories. (See Fig- 
ure 5-1.) 
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Figure 5-1. Directory Tree 

Partial tree diagram of V1 .2 Workbench disk showing how directories may con- 
tain subdirectories as well as files. 
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The LIST Command 

LIST prints the directory contents to the CLI window or 
printer (if you prefer). Here are some examples of how to ex- 
amine the contents of a directory: 

LIST RAM: Will make a list of the contents of the root directory of 

the ramdisk appear in the CLI window. 
LIST DFO: TO PRT: Prints a list of the contents of the root directory 

of the disk in DFO: on your printer. 
LIST DF0:C Will list the contents of the C directory on the disk in 

DFO: to your CLI window. 
LIST DF1:RAMIT/INCLUDES Lists the contents of the INCLUDES 

directory within the RAMIT directory on the disk in DF1:, to the 

CLI window . 
LIST DFO: OPT A This lists the names of every file on the disk in 

drive 0, including all directories and subdirectories. 

The NEWCLI and ENDCLI Commands 

NEWCLI is used to start another CLI window. This window is 
entirely separate from the current CLI window. You can run 
programs or enter commands in this window while the first 
window is busy doing something else. To activate the new 
window, just point the mouse anywhere inside it and click the 
left button. It's almost like owning more than one computer. 
Of course, you can use the NEWCLI command in this win- 
dow, which creates another CLI window. You can continue 
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this process as long as you want — your only limit is the 
amount of memory in your machine. This is an excellent ex- 
ample of the multitasking ability of the Amiga. ENDCLI closes 
and removes the CLI window in which the command was 
entered. 

NEWCLI Just type in the command and a new CLI window will im- 
mediately become available. You can type commands to it 
as if it were a second Amiga. 

ENDCLI Just type in the command and the CLI window will close 
down and disappear. 

This pair of commands is very useful. If you issue a com- 
mand that will take a long time (copying a large file, for in- 
stance), you can type in NEWCLI before you issue the time- 
consuming command, in order to have a separate CLI to work 
with while the other one is occupied. When the time-consuming 
command is finished, you can type in the ENDCLI command 
to its window and carry on using the new CLI that was called 
up with the NEWCLI command. 

The ASSIGN Command 

This command lets you assign one or more different logical 
names to a directory. This is useful if a program expects a 
group of files in a particular directory. If the files are in a di- 
rectory with a different name, you don't have to make a direc- 
tory with that name and copy the files to it. Simply assign the 
name of the directory the program is looking for to the direc- 
tory that contains the files. The ASSIGN command tells the 
Amiga that whenever it sees a reference to an assigned name, 
it should look in the directory it is assigned to. 

One example is very common. Many Amiga programs re- 
quire that the C directory of CLI commands be available 
somewhere. It's a common practice to use the COPY com- 
mand to move the C commands into a directory named C in 
the ramdisk, and then assign the logical name "C" to that di- 
rectory with ASSIGN C: RAM:C. Now, whenever the Amiga 
wants something from the C directory, it will look in the direc- 
tory RAM:C. Since files are loaded much faster from the 
ramdisk than a disk, commands will execute much faster. 

ASSIGN C: RAM:C Tells the Amiga that whenever it needs some- 
thing from the C directory, it can be found in the directory 
RAM:C. 
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ASSIGN D: RAM:RAMIT Tells the Amiga that whenever it needs 
something from the D: directory, it can be found in the directory 
named RAMIT in the ramdisk. This particular ASSIGN com- 
mand is used with the ASMINT program on the companion , , 

disk. ASMINT assumes a logical directory named D: exists | I 

somewhere and contains the files ASM, HEADER, EMACS, and 

so on. You can copy these files to any directory you want and 

have ASMINT look there by assigning the logical name D: to | 

that directory. ^~~^ 

ASSIGN By itself prints a list of logical directory names and their 
physical equivalents. 

The EXECUTE Command 

EXECUTE lets the Amiga execute a list of CLI commands writ- 
ten in a file. This type of file is called an execute file, a batch 
file, or a command file. 

EXECUTE DF1:RAMSTART Tells the CLI to treat the file 

RAMSTART in the root directory of DF1: as a series of CLI com- 
mands, as if they were typed in at the CLI. The RAMSTART file 
comes with the companion disk and contains all the commands 
required to copy the RAMIT directory and its files into the 
ramdisk. RAMSTART also contains the ASSIGN commands 
needed by the ASMINT program. 

EXECUTE RAM:MAKE Tells the CLI to treat the file MAKE as a se- 
quence of CLI commands. A make file is a convenient command 
file that contains the entire sequence of CLI commands required 
to assemble and link a program. They're commonly used to re- 
duce the amount of typing required to perform some task that 
requires multiple CLI commands. Use a text editor to write a 
make file or any other command file. 
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The RUN Command 

RUN allows you to perform a CLI command (or run a pro- 
gram from the CLI) without tying up the CLI you're using. 
RUN causes the command to execute in the background, 
which means the computer will execute the command and let 
you enter other commands at the same time. 

RUN DF0:C/COPY RAM:FILENAME TO DF1:FILENAME Causes M 
the COPY command to be executed in the background. The CLI 
window is left free for other commands. 

RUN RAM:MYPROGRAM Causes the CLI to start executing the I I 

program named MYPROGRAM from the ramdisk, while pre- ' — ' 
serving the current CLI window for use with other commands. 
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The CD Command (Change Directory/Current 
Directory) 

This command lets you move around within a group of direc- 
tories. When you're in a directory, it's as if that directory is the 
root directory. Other commands need not be preceded by that 
directory's specification. Here's an example: 

CD DF1: 

LIST You'll see the same thing as LIST DF1:. 

CD DF1:RAMIT/INCLUDES 

COPY A TO B Does the same thing as COPY 

DF1:RAMIT/INCLUDES/A TO DF1:RAMIT/INCLUDES/B. 
CD Prints out the current directory's name to the CLI window. 

Once you've used CD to move to a different directory, 
you'll stay there until you use CD to move again. 
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The Three-Step y 

Development of an Amiga 
Machine Language LJ 

Program 



This chapter covers the preparation of the source code that 
forms the foundation of any Amiga machine language pro- 
gram. The source code, as mentioned before, is a text file of 
MC68000 machine language instructions and program data. 

On the Amiga, as on many other computers, machine lan- 
guage programs are written using a text editor or word proces- 
sor. The text file is then translated by the assembler and 
linked with a linker. A machine language executable program 
is the final result. From the Amiga user's point of view, run- 
ning a finished machine language program is just like calling 
any command (such as COPY) on the Amiga. To run the file 
from the CLI, simply type the filename of the finished program. 

There are three steps in the construction of an Amiga ma- 
chine language program: 

• Write a source program file with a text editor. 

• Assemble the source program file, which creates an object 
file. 

• Link the object file to form an executable program load 

module. ! I 

Prepare the source (text) file of MC68000 instructions 
and Amiga system subroutine calls. The source file is always 
text and should not contain the usual formatting codes pro- 
vided by word processors. The simplest way to write source 
code files is to use the MicroEMACS program supplied with 
Amiga 1.2 Operating System upgrades by Commodore- Amiga. 
MicroEMACS is a high-performance editor that will make your 
composition easy because it uses the mouse and drop-down 
menus. It was used for the development of all program source 
file listings in this book and is usually referred to as simply 
Emacs. 
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Assemble the source (text) file using the ASSEM or 
ASM command. The ASSEM or ASM68010 creates a tempo- 
rary file that needs a final touch (linking) to become a full- 
fledged executable program. Here is how the ASSEM (or 
ASM) command is invoked from the CLI: 

ASSEM SOURCE -O OBJECT -C W150000 (Metacomco assembler) 
ASM SOURCE -O OBJECT (ASM68010 assembler) 

Remember that ASM is the name of the ASM68010 assem- 
bler that is found on the companion disk, and ASSEM is the 
name of Metacomco's Amiga assembler, part of the Commodore- 
Amiga Assembly Language Development package. 

These commands assemble file SOURCE to object code 
file OBJECT, using a work space of 150,000 bytes. It's very im- 
portant to provide a sufficiently large workspace for the ma- 
chine when using the Metacomco assembler. Usually 150,000 
bytes is adequate, sometimes even more is necessary. Even if 
the source text file is short, it may be that many additional 
files are included in the assembly. That situation may require a 
very large workspace. (See Chapter 8 for more information 
about include files.) 

The ASSEM command may be issued with additional pa- 
rameters and modifiers to cause disk or printer listings of the 
assembly. ASM68010 automatically allocates its workspace 
and requires no special command to set up a workspace of a 
specific size. ASM68010 ignores -C W150000 if it's present in 
the command. 

The command example below instructs the assembler to 
create a program listing file in addition to a file for the object 
code. The program listing file can be treated like any other 
Amiga text file: It can be edited, printed, copied, and so on. It 
shows the numerical instruction codes for each line of the 
source code file. 

ASSEM DFl:SOURCE -O DFl:OBJECT -C W150000 -L 
D¥l:OBJ.LIST (Metacomco) 

ASM DF1 SOURCE -O DFl:OBJECT -L DFl:OBJ.LIST (ASM68010) 

This example assembles a source file on DF1: to object file 
OBJECT on DF1: while creating a listing file OBJ.LIST (also on 
DF1:). The -L parameter causes a listing file to be created. 
Even if the source file is short, a large listing file may result if 
there are other included files. 
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Link the temporary file with the ALINK command. | 

This converts the temporary file created by the assembler into LJ 

a finished executable program with a name of your choice. 

The linking is required to knit sections of your program with j j 

memory references that are sometimes located in separate link ' — ' 

files. 

To understand linking, you must first realize that in the 
Amiga, no fixed memory addresses (except one — memory lo- 
cation 4) are used in programming. This is because all pro- 
grams must be able to operate anywhere they are placed in 
memory by the loading process. Unlike most eight-bit comput- 
ers, which run only one program at a time in a fixed memory 
space, the Amiga runs many programs simultaneously. All the 
Amiga programs are in memory at once, and can be loaded in 
any order. There is no way to know in advance where a pro- 
gram may reside when it's loaded and run. 

Therefore, an Amiga program is really a load module con- 
sisting of your code and the information required to adjust the 
addresses in the code according to the location in memory 
where it is loaded. The linker supplies some of this relocation 
information which makes up the load module. 

Sometimes numerical values that cannot be found in the 
include files are required by the assembler. Commodore has 
supplied a file named AMIGA.LIB (part of the Metacomco 
package) that contains these additional definitions. For the 
programs in this book, it isn't necessary to use the AMIGA.LIB 
file for linking. You can, therefore, always use the simplest 
forms of the ALINK command: 



ALINK OBJECT TO PROGRAM 

This example completes the simple assembly operation 
shown in the first example under ASSEM. First assemble 
SOURCE to OBJECT, and then link OBJECT to produce a final 
PROGRAM. 

When the source has been assembled and linked, run the 
final PROGRAM by entering PROGRAM from the CLI. 

If it were necessary to include AMIGA.LIB during linking, 
you could follow this example: 

ALINK OBJECT TO PROGRAM LIBRARY AMIGA.LIB 

The ASM68010 assembler has an alternate way of linking | J 

when all the program symbols are defined somewhere in the 
program. Since that's true for all the programs in this book 
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(symbols are defined either in the programs themselves or in 
include files merged with the program during assembly), it 
will be unnecessary to use any separate linker program with 
ASM. Its AUTOLINK feature can be used every time a pro- 
gram is assembled by preceding the source file name with an 
-A flag: 

ASM -A SOURCE -O OBJECT 

This command will assemble the file named SOURCE to 
an object file called OBJECT, and then AUTOLINK it. The re- 
sult will be an executable program (a load module) named OB- 
JECT that requires no further linking. Note that because 
ASM68010 is compatible with ASSEM from Metacomco, you 
can use it the same way as ASSEM, and use the usual method 
of linking with ALINK. Simply ignore the -A (AUTOLINK) 
feature if you wish to use ASM68010 with ALINK. 

A third alternative for linking is a public domain program 
called BLINK, which can substitute completely for ALINK. 
BLINK is available from many sources including user groups, 
bulletin boards, and vendors of public domain disks for the 
Amiga. 

A complete description of ASM68010 use, features, 
runtime flags (for instance, -A, -O, -L, and -I), and directives 
(conditional assembly, macros, listing control, and so on) is in 
Appendix B. 

The ASSEM and ALINK commands are completely de- 
scribed in the AmigaDOS Manual, published by Bantam Books. 
Pages 186-217 are devoted to descriptions of the ASSEM and 
ALINK programs. The linking process can be quite complex 
with scanned libraries, overlay files, and other features not re- 
quired for the programs presented in this book. 

A First Program: Assembling and Linking a Source 
Program 

The following sample program is called HELLO.ASM. It prints 
a short text message to the same CLI from which it is called. 
HELLO.ASM can only be used from the CLI. It's not compat- 
ible with the Workbench and icon system. Here is the se- 
quence of steps required to create and run HELLO.ASM: 

• Use a text editor to type in the program code for Program 1. 
(When saving the file from the text editor, use the filename 
RAM:HELLO.ASM.) 
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• Insert the assembler disk (either Metacomco or the companion J 
disk to this book) into DF1:. ^~~~ 

• Type the following CLI commands if using the Metacomco 
assembler: i ! 
DF1:ASSEM RAM:HELLO.ASM -O RAM:HELLO.OBJ -C W50000 
DF1:ALINK RAM:HELLO.OBJ TO RAM:HELLO 

DELETE RAM:HELLO.OBJ |_J 

These three commands assemble, link, and delete the 
temporary object file created by the Metacomco assembler 
prior to linking. The finished program will be waiting for use 
in the ramdisk. To run the program, just type RAM:HELLO 
from the CLI. 

• Type the following command using the CLI to perform both 
assembly and linkage using the ASM68010 assembler: 
DEV:RAMIT/ASM -A RAM:HELLO.ASM -O HELLO 

To run the program, just type RAM:HELLO from the 
CLI. 
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Before attempting to assemble any of the programs 
on the companion disk available with this book, you need 
to execute one or more of the three batch files included 
on the companion disk. 

• If you purchase the companion disk and have an Amiga 
with one megabyte or more of memory, you can speed 
up the assembly process by putting everything in the 
ramdisk. There are two batch files that will do this auto- 
matically for you. To put the system commands in the 
ramdisk, type EXECUTE DEV:RamDisk. This batch file 
will copy the system commands into the ramdisk (it will 
take a few minutes but it will be well worth your time). 
When it finishes, your commands will execute much 
faster, and you won't have to keep the Workbench disk 
in a disk drive. To move the assembler and include files 
into the ramdisk, type EXECUTE DEV:RamStartUp. This 
will copy the assembler and all include files into the 
ramdisk (again this will take a few minutes). The assem- 
bler will now operate much faster than when working 
with a disk-based system. 

• If you purchase the companion disk but have an Amiga 
with only 512K of memory, type EXECUTE DEV:StartUp. 
This will perform the assignments necessary to use the 
ASM68010 assembler. 

• If you're using the Metacomco assembler, check the as- 
sembler's manual for any necessary preparations. 
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Listing 6-1. HIWORLD.ASM 

;HIWORLD.ASM BY DANIEL WOLF 

.COPYRIGHT 1987 BY COMPUTE I PUBLICATIONS 

;09/10/87 

.**. A SIMPLE PROGRAM TO PRINT TO THE CLI WINDOW AND EXIT *** 

BRA _START ; BRANCH DIRECTLY TO BEGINNING OF PROGRAM 

SYSBASE EQU 4 



fTHE ONLY FIXED AMIGA ADDRESS, THE SYSTEM BASE! 
;IT CONTAINS THE ADDRESS OF THE EXEC LIBRARY BASE 



LVO.OPENLIBRARY EQU 5FFFFFDD8 
LVO . CLOSELIBRARY EQU ?FFFFFE62 
LVO. OUTPUT EQU SFFFFFFC4 
LVO. WRITE EQU $FFFFFFD0 



;EXEC LIBRARY OFFSET 
;EXEC LIBRARY OFFSET 
fDOS LIBRARY OFFSET 
;DOS LIBRARY OFFSET 



JUST MACRO; ROUTINE 
JSR LVO.\l(A6) 
ENDM 

.»** BEGIN HERE *** 

START 
"MOVEA.L SYSBASE, A6 
LEA _DOSNAME,Al 
MOVEQ.L #0,D0 
JUST OPENLIBRARY 
MOVE.L D0.A6 
BEQ _STARTERROR 

JUST OUTPUT 

MOVE.L D0.D1 
MOVE.L # MESSAGE, D2 
MOVE.L #LENGTH,D3 
JUST WRITE 



;A MACRO TO CALL SPECIFIC NAMED ROUTINE 



• PUT POINTER TO NAME IN Al 

;DON'T CARE WHICH KICKSTART VERSION 

;OPEN DOS LIBRARY 

;KEEP LIBRARY POINTER IN A6 NOW 

;0 MEANS ERROR 

;SET UP CLI WINDOW AS OUTPUT FOR TEXT 

; ADDRESS OF OUTPUT FILE HANDLE 

;ADDRESS OF MESSAGE TEXT 

; NUMBER OF CHARACTERS IN MESSAGE 

; PRINT MESSAGE TO CLI WINDOW 



.*** NOW CLEAN UP AND EXIT TO SYSTEM *** 



MOVE.L A6.A1 
MOVE A. L SYSBASE, A6 
JUST CLOSELIBRARY 
RTS 

_STARTERROR 
MOVE.L #20, D0 
RTS 



r CLOSE THE DOS LIBRARY 

;EXIT BACK TO WHERE THIS PROGRAM CAME FROMI 



J PUT ERROR CODE IN D0 IF DOS WON'T OPEN 
;AND EXIT NOW1 



;*** DATA DECLARATIONS *** 

_DOSNAME 

DC.B 'dos. library' ,0 

MESSAGE 
DC.B ' HELLO WORLD ',13,10 

LENGTH EQU "-MESSAGE 

DC.W 

END 



;NAME AS REQUIRED BY OPENLIBRARY 

,-TEXT MESSAGE WITH RETURN, LINEFEED 
; PC-LABEL = LENGTH OF MESSAGE 
.•WORD-ALIGN THE PROGRAM COUNTER 
j END DIRECTIVE TO ASSEMBLER 
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Reference Section 

Text Entry, Assembly, and Link Commands for this 
Book 

The steps used with this example are also used to enter, 
assemble, and link all the other programs in this book. 
The procedures are repeated below, step by step, for 
reference. 

Text Entry Procedure for all Files and Program Listings 
in this Book 

• Use the EMACS text editor to type in text. 

• Use the save as project menu selection to save the text 
file with the appropriate name. 

Assembly and Link Procedure for Program Listings in 
this Book — Metacomco Assembler 

• Use the CLI to type in the following assembler 
command: 

ASSEM SOURCEFILENAME -O OBJECTFILENAME 

• Use the CLI to type in the following linking command: 
ALINK OBJECTFILENAME TO PROGRAMFILENAME 

• Use the CLI to delete the intermediate object code file: 
DELETE OBJECTFILENAME 

• Use the CLI to run the program: 
PROGRAMFILENAME 

Assembly and Link Procedure for Program Listings in 
this Book— ASM68010 Assembler 

• Use the CLI to type in the following assembler autolink 
command: 

ASM -A SOURCEFILENAME -O PROGRAMFILENAME 

• Use the CLI to run the program: 
PROGRAMFILENAME 

SOURCEFILENAME, OBJECTFILENAME, and 
PROGRAMFILENAME are dummy names to indicate that 
some directory/file name combination is required here. 
Complete examples of these command sequences are 
shown above for real source, object, and program files. 
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Commands to the assembler, called directives or assembler 
directives, make programming more convenient. This chapter 
introduces directives and presents enough information to get 
you started using the more common ones. A comprehensive 
reference section on assembler directives is found in Appen- 
dix A. 

Directives are sometimes called pseudo-ops because they 
look like op-codes, but are not recognized by the MC68000 
microprocessor. They are only read and interpreted by the 
assembler. 

Three of these directives are so important that separate 
chapters are devoted to them. Those three directives are IN- 
CLUDE, MACRO, and IF (conditional assembly). 

The simpler directives DS.x, DCx, EQU, and END are 
presented below. 

The DS.jc Directive 

The DS.x directive Declares Storage for program data. It is 
used frequently in machine language programs to set aside 
memory at the time of assembly. You may wish to limit the 
use of this directive and use dynamic memory allocation in 
your program to create storage areas and delete them as 
needed. The techniques for dynamic memory allocation in j 

programs are shown later. Here are examples of using DS.x 
(where x stands for the MC68000 size specifier, B, W, or L): 

MESSAGE 

DS.B 80 ; DECLARING AN 80-BYTE STORAGE AREA AT 'MESSAGE' 

BUFFER 

DS.B 132 ; DECLARING A 132-BYTE STORAGE AREA AT 'BUFFER' 

POINTERLIST 

DS.L 16 ; DECLARING 16-L0NG WORD POINTER ARRAY NAMED 
; 'POINTERLIST' 
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When the assembler sees a DS.x directive, it makes room 
in the object code accordingly. The above examples show how 
a block of memory can be incorporated directly into a 
program. 

The DC* Directive 

The DCx directive Declares a Constant value. In addition to 
declaring specific memory storage requirements using the DS.X 
directive, you can declare specific labeled variable values and 
constants in your code using the DC* (where x stands for the 
size specifier). All the programs in this book make extensive 
use of the DC.x directive to provide initial values for certain 
program variables, and to create labeled storage locations for 
pointers that have an initial null (0) value. As you read 
through the program listings, you'll see dozens of examples of 
DC.x that lay out text strings as well. Text strings in the 
Amiga usually end with a byte. Here are some examples of 
DC.x usage: 

WINDOWPTR 

DC.L ; STORAGE FOR LONG-WORD POINTER, FILLED 

; LATER 

MYMESSAGE 

DC.B 'Hello World',0 ; EXAMPLE OF NULL-TERMINATED AMIGA TEXT 

WINDOWTITLE 

DC.B 'My Window',0 ; EXAMPLE OF TEXT FOR A WINDOW TITLE 

POINTERARRAY 

DC.L 0,0,0,0,0,0,0,0 ; Layout for EIGHT LONG-WORD POINTERS 
; (ADDRESSES) INITIALIZED TO NULL (0) 

When the assembler finds the DC* directive, it places the 
data constant that follows it into the program. 



The EQU Directive 

The EQU (EQUate) directive assigns a label to a specific nu- 
merical value. This is handy for parameters best defined at the 
["""J beginning of the program. 

1 For example, you may want to create size values for all 

the windows in a program, at the beginning. You could create 
f**j equates called WINDOWH and WINDOWV. To assign win- 
' dow sizes to windows within the program, you would merely 
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enter these two labels when the window size parameter is re- 
quested. Then, if you want to change all the window sizes, 
rather than search through the program for every window def- 
inition, you can simply change the values in the EQUate state- 
ments at the beginning of the program. 

This is how the equates files are written (INTEQUATES.ASM, 
for instance). Here are some examples: 



MAX-XSIZE EQU 639 
MAX-YSIZE EQU $20 



SETS MAX-XSIZE EQUAL TO 639 (DECIMAL) 
SETS MAX-YSIZE EQUAL TO HEX 20 (32 
DECIMAL) 

Later on you can use these values in the following way: 

MOVE.W #MAX_XSIZE,D1 ; THIS MOVES WORD VALUE 639 INTO Dl 
MOVE.L #MAX_YSIZE,D2 ; MOVES LONG-WORD VALUE $20 (32 

; DECIMAL) INTO D2 

The programs in this book use the EQU directive exten- 
sively. In most of the programs the EQU directive is used at 
the very beginning of the program to define certain symbols 
that control conditional assembly in other parts of the pro- 
gram. Conditional assembly (using the IF directive) is pre- 
sented in a separate chapter. Here are some examples of using 
EQU simply to define a symbol: 

DOS EQU 1 
INT EQU 1 
GFX EQU 1 

An equate does not reserve storage in your program. In- 
stead, the EQU directive is used to define a value in the sym- 
bol table during assembly. Then, other portions of the program 
can use references to these symbols to control conditional 
assembly. ! 



END Directive 

END may appear only once in a source file being assembled. 
It tells the assembler to stop. It's not necessary to have an 
END directive, but if you want the assembler to assemble only 
the first half of your program, the END pseudo-op will allow 
this. 
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Arithmetic Operators 

There are several directives that can be used to perform some 
simple arithmetic computations (operations) during assembly. 
Here are some examples: 

The logical OR operator (!). The following code illus- 
trates the use of the logical OR operator, symbolized by the 
exclamation point (!): 

MOVE.L #MEMF_CHIP!MEMF_CLEAR,DO ; USED WHEN ALLOCATING 

; MEMORY 

This line of source code means the assembler should com- 
bine (using the Boolean OR function) two different symbols' 
numeric values into a single numeric value. In this case 
MEMF_CHIP has the decimal value of 2 (0000 0010 binary) 
and MEMF_CLEAR has a decimal value of 16 (0001 0000 bi- 
nary). When the assembler encounters the ! directive, it com- 
bines these two values into a single decimal value of 18 (0001 
0010 binary) in the object code. 

The integer division operator (/). The following line of 
source code demonstrates the use of the integer division oper- 
ator (/): 

M0VE.L #TICKSPERSEC0ND/2,D1 

This line of code tells the assembler to divide the value of 
TICKSPERSECOND by two, prior to generating code for it. 
The TICKSPERSECOND symbol has the numerical value of 
50 in the Amiga (see DOSEQUATES.ASM). In this example, 
the assembler would place the value 25 into Dl. This type of 
code is used, in several of the programs in this book, along 
with the AmigaDOS DELAtf function to cause a program to 
wait for a specified period of time without tying up the 
microprocessor. A typical usage of this construction is: 



M0VE.L 


#TICKSPERSEC0ND,D1 




DOSLIB 


DELAy 


; USE AMIGADOS TO DELtf 1 FULL 
; SECOND 


M0VE.L 


#TICKSPERSEC0ND/4,D1 




DOSLIB 


DEL/W 


; USE AMIGADOS TO DELW 1/4 
; SECOND 



Integer division should only be used with integers. 
The shift left operator («). The shift left operator, sym- 
bolized by two less-than signs («), shifts a binary number 
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one bit to the left, essentially multiplying it by two, as in the 
following example: 

MOVE.L #TICKSPERSECOND«,Dl ; SHIFTS TICKSPERSECOND 1 BIT 

■ LEFT 
DOSLIB DELtf ; USE AMIGADOS TO DELPU 2 FULL 

; SECONDS 

There are several other arithmetic operators used in the 
same ways shown in the preceding examples. They include: 



Operator 


Effect 


+ and — 


Add and subtract 


♦and/ 


Multiply and divide 


1 


Logical OR 


& 


Logical AND 


» 


Right shift (divide by two) 


« 


Left shift (multiply by two) 



Refer to Appendix A for comprehensive information on 
the use of assembler directives and arithmetic operators. 
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In preceding chapters, you've seen references to include files. 
Include files are pieces of source code that are merged with a 
program during assembly. They provide programmers with a 
sensible way to manage program development. Include files 
are generally short, easily read, easily altered files that per- 
form a single function or provide a library of equates for the 
main program to use. They bring modular programming to 
machine language. 

The Include Files and the Kernel 

The Amiga is equipped with 256 kilobytes of kernel software. 
The kernel is full of useful routines and system constants that 
do most of the Amiga's work. The ROM kernel code contains 
routines for opening and managing windows, operating the 
mouse, keyboard sensing, multitasking control, and more. 

Many of the kernel routines have names and known entry 
points for use by C and machine language programmers. 
There are also hundreds of system constants, most of which 
are offsets relative to known memory locations. The art of pro- 
gramming the Amiga, whether in C or machine language, in- 
cludes the proper use of these kernel routines, system 
constants, and offsets. 

Probably the most common use of include files is provid- 
ing a library of the kernel routines, along with labels. If these 
equates had to be defined in each piece of source code, the 
programmer could waste hours looking up addresses and typing. 
The include files allow you to take care of this time-consuming 
chore only once, after which a simple include directive will in- 
sure that the necessary equates will be provided at the time of 
assembly. This also keeps source code files smaller (because 
the equates are part of a separate file) and reduces the likeli- 
hood that a difficult-to-find typing error will interfere with the 
program's operation. 
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Amiga Include Files I | 

The include files provided with the Metacomco assembler are 

lists of the named kernel routines and constants, and their val- , -j 

ues or addresses. The include files are numerous, and each L I 

one contains name and value information for a related group 

of kernel routines and constants. The machine language in- ,- -. 

elude files all end with .1 (such as TYPES.I, INTEQUATES.I). [J 

The Amiga ROM Kernel Reference Manual: Libraries and 
Devices, published by Commodore, contains printouts of the 
include files. You can also read the include files by printing 
them out (from the Metacomco disk) using AmigaDOS CLI 
commands such as TYPE FILENAME TO PRT:. 

Because the early machine language development system 
for Amiga was actually a SUN Microsystems workstation with 
a UNIX operating system and many megabytes of memory, 
the Amiga include files are fairly complex. 

• The include files are extremely long. The disk versions are 
nearly identical to those printed in the Libraries and Devices 
manual. They include much descriptive system documenta- 
tion commentary. This makes them valuable reference docu- 
ments, but a little unwieldy when using a "plain vanilla" 
Amiga as the development system. They are so large that it's 
difficult to use them when programming an unexpanded 
Amiga. 

• The include files from Amiga contain special macros that 
automatically convert the structure field names from the for- 
mat in which they're presented (similar to the way they 
would be declared in a C program) into their numerical 
equivalents, during assembly. That means the actual numeri- 
cal values of most structure field names are not given explic- 
itly in the include files. Because library offset values are not 
explicitly stated either (they are found in AMIGA.LIB), it is 
necessary to link with AMIGA.LIB when using these include 
files. 

• Experienced machine language programmers should take ad- 
vantage of the clever and complete constructions available in 
the Amiga include files. It's probably wise to make a separate 
working copy of each of them with comment lines deleted to 
make them more manageable in length. You could write a 
program to strip any lines beginning with a semicolon or an 
asterisk. 
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Include Files for Use with This Book 

This book presents several include files that contain: 

• Lists of symbolic equates for use with DOS, Graphics, Exec, 
and Intuition. These are all fairly short (total of about 10K) 
and can be expanded by studying the ROM kernel manuals. 
For additional library vector offsets, see Appendix D of the 
Exec manual. For additional named structure field offsets, 
compare the tables in this volume with the listings in the In- 
tuition manual. 

SYSEQUATES.ASM — Numerical definitions of general Amiga 
system variables. 

DOSEQUATES.ASM— Same for those specific to AmigaDOS 
(DOS library). 

GFXEQUATES.ASM— Same for those specific to Graphics 
(Graphics library). 

INTEQUATES.ASM— Same for those specific to Intuition (In- 
tuition library). 

• Convenient macros for use with the listings in this book and 
your own programs. This is a fairly short list that you can ex- 
pand with additional macros of your own design. 

MACROS.ASM— 68000, system, DOS, graphics, intu- 
ition, and math macros. There are a few additional macros 
that are in the other specific support files. Since these addi- 
tional macros are specific to the tasks carried out by the sup- 
port code files, they've been placed there. The MACROS.ASM 
file only contains the most general and widely used macros. 

• Special support code for parts of the Intuition system (win- 
dows, text, menus, gadgets, requesters). These have been 
written to simplify use of the Intuition resources and to dem- 
onstrate their use in the sample programs, and contain both 
subroutines and a few specific macros that can simplify your 
source programs. 

WINDOWS.ASM 

TEXTS.ASM 

MENUSASM 

GADGETS.ASM 

REQS.ASM 

• Additional support code files to simplify program develop- 
ment when using floating-point and transcendental math. 
MATH.ASM 
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• A program fragment, which is needed for almost all pro- | 
grams on the Amiga, that performs the functions of a grace- ^ — ' 
ful start and ending of a program. This program fragment 
permits the Amiga operating system to recognize the pro- 
gram when it starts running, and then perform appropriate ^— ' 
preliminary tasks, depending on whether the program is acti- 
vated from the Workbench (clicking an icon) or started by a j I 
CLI command (by entering programname or RUN program- l — ' 
name at the CLI). This universal program fragment is called: 

STARTUP.ASM 

You should type in and copy these files to the INCLUDES 
directory of your machine language work disk. In a later chap- 
ter you'll find instructions for creating a work disk for machine 
language program development. The include files mentioned 
above are required by the other programs in this book. The 
typing job is long, but it can be avoided if you have the com- 
panion disk to this book, which contains all of these files. The 
include files on the Metacomco disk are not used by the pro- 
grams in this book. 

If you opt to type the include files, you can leave out the 
comments in order to reduce the amount of typing necessary. 
Using MICROEMACS or another text editor will simplify your 
work. In the end, you'll have a set of compact, versatile, and 
easily expanded include files. 

Using Include Files in a Program 

Include files are called into your program at the time of assem- 
bly with the INCLUDE assembler directive. There should be 
one directive for each of the files to be included. You should 
write the include directives at the beginning of your source I i 

code. As the assembler scans the source file, each time it s ~- ' 

comes upon an include directive, it will locate the named file 
and merge it into the workspace used by the assembler. That I 

means that the workspace contains one long file built from ^ — ' 

your source file and all the include files. 

In the following examples, it is assumed there is some di- 
rectory called INCLUDES that contains all the include files. "-J 
For convenience, this is often a ramdisk directory. 

U 
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INCLUDE *'INCLUDES:MENUS.ASM" 

INCLUDE "INCLUDES:MATH.ASM" 

INCLUDE "INCLUDES:SYSEQUATES.ASM" 



PUTS INCLUDES:MENUS.ASM IN 

WORK AREA 

PUTS INCLUDES:MATH.ASM INTO 

WORK AREA 

PUTS INCLUDES:SYSEQUATES.ASM 

INTO WORK AREA 



The assembler will look for the listed files in the IN- 
CLUDES directory. If they're found, they are loaded into the 
assembler's workspace at exactly the point in the source file 
where the include directive appears. 

The Header File 

The header file provides a shortcut to including files based on 
the fact that any file can be included within another. 

A header file is simply a list of include commands. (The 
header file used with all the programs in this book is printed 
in Chapter 9, under the heading Conditional Use of the In- 
clude Directive.) Because many of the same include files are 
needed by most programs, the include process was simplified 
by using the header to take care of all the other includes 
needed for a program. In order to understand the operation of 
the header file fully, you'll need to understand conditional as- 
sembly, which is discussed in Chapter 9. 

The header file is called with a single include command: 

INCLUDE "HEADER" 

The header file will then choose the include files needed 
for the program being assembled. 

Within the Equate Files 

When you write your program, you'll call the needed kernel 
routines by name. The equate files remove the responsibility 
of entering the addresses of these routines and constants. They 
enter the addresses of the constants and routines for you. 

The equate files also provide definitions of system tables 
called structures, which will be discussed in more detail at a 
later time. Here is a section of the INTEQUATES.ASM include 
file that contains values of constants used by Intuition: 



BOOLGADGET 


EQU 


$1 


BORD.BACKPEN 


EQU 


$5 


BORD.COUNT 


EQU 


$7 


BORD.DRAWMODE 


EQU 


$6 


BORD.FRONTPEN 


EQU 


$4 
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This equate file contains constant values for dozens of 
symbolic labels used by Intuition. Those shown here are 
mostly offsets into the BORDER structure (a type of memory 
data table). For example, BORD.COUNT is equal to seven. 
This is because the COUNT for a border is found seven bytes 
into the structure. The COUNT is the number of pairs of x,y 
points that make up the border endpoints. If a BORDER has 
five endpoints, the number 5 should be located exactly seven 
bytes from the beginning of the BORDER structure. Putting a 
value of 5 in that location could be done in the following way: 



LEA BORDER.A0 
MOVE.W #5,BORD.COUNT(A0) 



; PUT ADDRESS OF THE BORDER 
; STRUCTURE INTO AO 
; PUT FIVE INTO A WORD LOCATED 
; SEVEN BYTES FROM ADDRESS IN AO 
;(THE 
; ; BASE ADDRESS OF THIS BORDER 

; STRUCTURE) 

Programmers don't have to memorize the fact that 
BORD.COUNT equals seven, or look it up on a table. They 
only need to include an equate file and keep handy a list of 
the shorthand names for constants and routines in the kernel. 

As you read through this book, you will see many exam- 
ples in which names are used where you might expect to see 
numbers. Remember that numerical values are assigned to 
these names in an equate file. 

It's important to use the names instead of actual numeric 
values whenever possible. The reason is that the manufacturer 
might change the locations of these constants and routines 
within the kernel. If there are such changes in the future, the 
equate files will also be changed so that using the familiar 
names will result in the correct numerical values being gener- 
ated by the assembler. 

Whenever you see a strange variable name or odd com- 
bination of characters used without any apparent definition, 
try looking up the unfamiliar word or characters in the include 
files. 

It's wise to be careful about the order of your include as- 
sembler directives within the source code. For instance, while 
it is permissible to include a file within an included file, be 
careful not to nest included files so deeply that they're difficult 
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r~""1 to follow. It would be better programming practice to do all in- 
I - eluding early in the main source code. 

If you fail to include a file with necessary symbol defini- 
r ~" a ] tions for your program, the assembler will report undefined 
' > symbol errors and the assembly will fail. When you see this 
sort of error, check your include files first to make sure you 
r"~ | have included all necessary files. 
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Macros and Conditional 
Assembly 



Macros 

A macro is typically a short, frequently used sequence of ma- 
chine language instructions. Once you've assigned a name to 
the macro, the assembler treats it as if it were a new instruc- 
tion. When assembled, the macro is expanded into its defined 
list of instructions at that point in your program. You can see 
that a macro is similar to an include file, but it contains in- 
structions rather than data. 

Macros usually have one or more parameters as well. The 
parameters are symbols from the source program. The macro 
utilizes them as input data. This is a feature that allows mac- 
ros to do things subroutines cannot. 

Macros can contain directives (commands) to the assem- 
bler, so that as they are encountered in the source program, 
the assembler may arrange them in different ways in the as- 
sembled code. Once you use a few macros, they become indis- 
pensable power tools and can make your programming much 
easier. Macros are widely used throughout this book, and a 
listing of them is provided in MACROS.ASM. You're free to 
make additional macros and add them to the MACROS.ASM 
file. Macros make machine language extensible; you can define 
efficient new instructions with the names and syntax of your 
choice. 

Here is an example macro: 

ZERA MACRO ; AN 

SUB.L \ 1, \ 1 
ENDM 



UJ 
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This short macro definition is called ZERA. Its purpose is .- - - 

to clear an address register (set it to 0). It turns out that there | i 

is no direct instruction to do this on the MC68000. There is a 

CLR.L Dm instruction, which can clear a data register, but you ,- - - 

can't use it with an address register. Use the macro as a short- j^J 
hand instruction name to clear an address register. When you 
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want to use it in your program to clear address register A2, 
write: 

ZERA A2 

It will behave as if it were an instruction to clear address 
register A2. When the assembler encounters this macro, it sub- 
stitutes the instruction SUB.L A2,A2 at that point in the code. 
The A2 in the usage example is called a parameter. It's 
matched with the symbol \ 1 found in the macro definition. 
When you see the symbol \ 1 in a macro definition, it should 
be read as parameter number 1. In this case, there is one pa- 
rameter, A2. So when the assembler sees: 

ZERA A2 

it assembles it as: 

SUB.L A2.A2 

This instruction tells the MC68000 microprocessor to sub- 
tract A2 from itself. Therefore, it has the effect of clearing A2. 

As you can see, Macro definitions make MC68000 ma- 
chine language extendible with as many additional instructions 
as you wish to create. A clever and energetic programmer can 
create a higher-level language by using macros. 

The following example creates a macro to simplify the 
process of calling a ROM kernel library subroutine: 

LIBCALL MACRO ; LIBRARY, ROUTINE (TWO 

; PARAMETERS) 
M0VE.L \1,A6 
JSR LV0.\2(A6) 

ENDM 

This macro uses two parameters, the first ( \ 1) is the label 
at which you have previously stored a library base address. 
The second parameter ( \ 2) is the short name of the routine 
you want to use in that library. The ASM68010 assembler 
starts the names of all library routines with WO., and this 
macro puts those letters in place for you. Here's an example 
showing how this macro is used in a program: 

LIBCALL D0SBASE,WRITE 

The program code generated by this macro invocation is: 

MOVE.L D0SBASE,A6 ; PUTS PARAMETER #1 INTO A6 
JSR LV0.WRITE(A6) ; JSR TO LVO.PARAMETER #2 
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Nesting Macros , ; 

A macro may contain another macro's name. Encountering j j 

such a circumstance, the assembler will expand one macro 
within the other. The following example nests the LIBCALL 
macro inside another macro: 



DOSLIB MACRO 

LIBCALL -DOSBASE, \1 
ENDM 

For the sake of this example, you must imagine that else- 
where in the program you stored an address from the DOS li- 
brary at an address labeled DOSBASE. This macro uses 
LIBCALL. LIBCALL's \ 1 (parameter number 1) becomes 
DOSBASE. The DOSLIB macro only has one parameter — the 
name of the DOS library routine you wish to call. Here's an 
example of using DOSLIB: 

DOSLIB READ 

This is the code the assembler will generate when it en- 
counters this macro: 

MOVE.L _D0SBASE,A6 
JSR LV0.READ(A6) 

This code is identical to the code generated by 

LIBCALL _DOSBASE,READ 

The LIBCALL macro nested in the DOSLIB macro is 
shorter and quicker to type in. 

Macros vs. Subroutines 

Using macros can make programming in machine language al- 
most as easy as programming in C or some other high-level 
language. Convenient symbolic macro names with simple, 
sensible parameters can substitute for a great deal of repetitive 
typing. Macros make it convenient to create new instructions 
when no simple MC68000 instruction will do the job. From 
the programmer's perspective, macros turn lengthy sequences 
of code into short symbolic names, almost like keywords in 
BASIC. 

Macros are especially useful when code sequences are 
used repeatedly with slight variations which can be accommo- 
dated by passing parameters. In fact, the ease of passing pa- 
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rameters to macros is one of their principal advantages over 
subroutines. 

Using subroutines instead of macros is a programming de- 
sign decision. If you use many long macros, you'll end up 
with a very long object file, while your source code remains 
compact. Using large numbers of subroutines may have the 
opposite effect, to some degree: The object code generated by 
the assembler will be more compact. 

Subroutines only appear in your code once. They can be 
used repeatedly without generating additional code, but in or- 
der to use them, you'll probably have to create code that 
passes parameters to them. 

Some Macro Examples 

A family of macros used throughout the programs in this book 
is printed in the next chapter. This family is used in almost all 
the programs and should be typed in according to the instruc- 
tions given. Here are some additional examples of macros as a 
review, to insure that you understand the concept. 

ZERO MACRO 

MOVEQ.L#0,\1 
ENDM 

This macro clears a data register. For example, if you wish 
to clear data register DO, you simply write: 

ZERO DO 

The following macro pushes the contents of the desired 
register or registers onto the stack. 

PUSHREG MACRO 

MOVEM.L \1,-(SP) 
ENDM 

If you wish to save the contents of DO, Dl, and D2 while 
those registers are temporarily used for something else, you 
can use the following line of code: 

PUSHREG D0-D2 

The following macro pulls data from the stack and places 
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it into the registers specified in \ 1: 

PULLREG MACRO 

MOVEM.L (SP)+,\1 
ENDM 

If you wish to restore the contents of DO, Dl, and D2 
from the previous example, use the following line of code: 

PULLREG D0-D2 
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Conditional Assembly 

Another group of assembler directives allow the programmer 
to write source code which may or may not become part of 
the executable program when it's assembled. These condi- 
tional assembly directives are instructions to the assembler 
either to assemble a section of code or skip over it, based on 
whether certain conditions are satisfied. 

The conditionals do not affect the actual program except 
by controlling what code is assembled into the object program. 
Don't confuse these conditional assembly directives with the 
condition codes of the MC68000 microprocessor, which are 
used with other MC68000 instructions to control the program 
flow. 

IFxandENDC 

Four of the conditional directives are used frequently in the 
programs in this book. Comprehensive documentation on con- 
ditional assembly can be found in Appendix B. The four com- 
monly used conditionals are: 

IFD Assemble if a symbol is defined. , - , 

IFND Assemble if a symbol is not defined. [_ i 

IFC Assemble if a symbol is the same as another symbol. 

IFNC Assemble if a symbol is not the same as another symbol. 

Whenever the IF* conditional directive is used, it precedes I — I 
the section of program source code to be affected by the con- 
dition. After the section of code that is under control of the f" j 
conditional, you must use: L I 

ENDC Ends conditional assembly. 
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Here are some examples. The first example shows a com- 
bination of assembly directives. 

IFD DOS 

INCLUDE 'DOSEQUATES.ASM* 

ENDC 

The DOSEQUATES.ASM file will only be included if the 
symbol DOS is defined somewhere in the program. 

The next example sets JAM1 equal to only if it has not 
been defined elsewhere. 

IFND JAM1 
JAM1 EQU ; DEFINE THE LABEL IF NOT ALREADY DEFINED 

ENDC 

The next example uses the DOSPRINT macro to print out 
a message if the symbol named STRING contains the value 
HELIO at assembly time. 

IFC STRING/HELLO' ; COMB\RE STRING TO HELLO 

DOSPRINT STDOUT,#MESSAGE 

ENDC 

The last example is used frequently with macros. In effect, 
it says, "If the first parameter ( \ 1) is not equal to a blank 
(empty string), then move that parameter into DO." 

IFNC ' \ 1*," ; IF PARAMETER ONE IS NOT BLANK 

MOVE.L \1,D0 

ENDC 

To see more examples of conditional assembly, review the 
MACROS.ASM file and the HEADER file under the heading 
"Conditional Use of the Include Directive," below. 

Conditional Assembly Within Macros 

Macros can use conditional assembly to make them even more 
flexible. In this example, the macro sets up a pen color for 
graphics (the graphics functions are presented later). The 
macro uses DO to hold the pen number. If the program al- 
ready has the color number in DO, the macro doesn't need to 
move it there. The macro can skip over that part and just call 
the SETAPEN graphics function. 
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SETAPEN MACRO 




PARAMETER ONE IS RASTPORT 


u 


i 




PARAMETER TWO IS COLOR # 


GFXPUSH 




MACRO NESTED WITHIN THIS 








MACRO TO S/fl/E REGISTERS 


1 1 


IFNC 


' \2\" 


IF SECOND PARAMETER EXISTS 


u 






(IS NOT A BLANK) 


MOVE.W 


\2,D0 


MOVE SECOND PARAMETER TO 




ENDC 




DO 

END OF CONDITIONAL ASSEMBLY 


u 


GFXLIB 


SETAPEN, \1 


CALL THE GRAPHICS FUNCTION 
SETAPEN 




GFXPULL 




RESTORE THE REGISTERS 
PUSHED WITH GFXPUSH 




ENDM 









In the next two examples that use the macro above, the 
macro takes advantage of the conditional assembly. In the first 
example, the assembler will recognize that there is no second 
parameter (color number) specified and won't assemble the 
part of the SETAPEN macro that contains the instruction 
MOVE.W \2,D0. 



MOVE.W 
SETAPEN 



#3,D0 
RP 



PLACE COLOR NUMBER INTO DO 

DON'T USE SECOND PARAMETER COLOR 

NUMBER 

BECAUSE ITS ALREADY IN DO 



In the next example, the assembler recognizes that the 
second parameter has been provided and the line containing 
MOVE.W #3,D0 will be assembled as part of the macro. 



SETAPEN RP,#3 



USE MACRO TO PLACE COLOR NUMBER THREE 

INTO DO 

AND CALL THE SETAPEN FUNCTION 



Conditional assembly within the SETAPEN macro allows 
you to enter a color number in DO one time and subsequently 
use the SETAPEN macro several times with that color num- 
ber. The assembler leaves out the unnecessary line of code 
(MOVE.W \2,D0) in each case. This shortens the object file 
generated by the assembler and makes it run faster. 

The MACROS.ASM file printed in the next chapter shows 
other examples of conditional assembly within macros. Most 
of the program listings use this flexibility by making reference 
to macros with different numbers of parameters. Using condi- 
tional assembly within macros lets a macro do several slightly 
different things, depending on the needs of the programmer. 
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Conditional Use of the Include Directive— The 
Header File 

Another valuable use for conditional assembly was shown 
briefly above: the use of conditional assembly to control the 
include process. 

Several include directives may appear near the beginning 
of a program. They are used early in the source code to bring 
relevant symbol definition files, macro files, and other files 
into the object code before they're called on by the code that 
follows. 

As mentioned earlier, a header file can serve as a handy 
tool to simplify this section of a program. The best way to use 
a header file is to conditionally assemble all available include 
files. Then, the programmer can simply define the symbols 
that control, including the specific files needed by the 
program. 

Program 9-1 is a header file used by all the programs in 
this book. There are a few includes that are always needed, 
and they're not controlled by conditional assembly. For in- 
stance, all the programs need the SYSEQUATES.ASM, 
MACROS.ASM, and the STARTUP.ASM files. 

The symbols used to control most include directives are 
simple three-letter codes that are easy to remember. 

If you write the following opening lines of a program 
source file: 

DOS EQU 1 

INT EQU 1 

INCLUDE "HEADER" 

the header will insure that the following files are included: 

• DOSEQUATES.ASM 

• INTEQUATES.ASM 
SYSEQUATES.ASM 
MACROS.ASM 
STARTUP.ASM 



• 



All the other files controlled by conditional assembly in 
the HEADER will be ignored since their control symbols are 
not defined. In other words, IFD is false for the other files, 
and conditional assembly will skip GFXEQUATES.ASM, 
WINDOWS.ASM, MENUS.ASM, GADGETS.ASM, and the 
rest (see Program 9-1.) 
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All the programs in this book, except HIWORLD.ASM, 
use the HEADER file and the corresponding symbols. Table 9- 
1 is a list of the three-letter symbols used to control condi- 
tional assembly in this book. 

Table 9-1. Conditional Assembly Symbols for HEADER and 
STARTUP.ASM 





HEADER 


STARTUP.ASM will 




Symbol 


will include 


open/close 


Comments 


INT 


INTEQUATES.ASM 


Intuition Library 




DOS 


DOSEQUATES.ASM 


AmigaDOS Library 




GFX 


GFXEQUATES.ASM 


Graphics Library 




MAT 


MATH.ASM 


MathFFP Library 




TRA 




TransMath Library 




WIN 


WINDOWS.ASM 






MEN 


MENUS.ASM 






GAD 


GADGETS.ASM 






REQ 


REQS.ASM 






TXT 


TEXTS.ASM 






HEX 






Controls as 



FFP 



WBC 



MATH part of 

MATH.ASM 

Controls assembly of FFP 

MATH part of 

MATH.ASM 

Controls assembly of 

WORKBENCH CONSOLE 

in STARTUP.ASM 



Listing 9-1. The HEADER File Used in Programs in This Book 

******************************** HEADER. ASM BY DANIEL WOLF 

COPYRIGHT 1987 BY COMPUTE! BOOKS 

08/12/87 



NOLIST 

IFND DOS 
DOS EQU 1 
ENDC 

IFND INT 
INT EQU 1 
ENDC 

IFD DOS 
DOSE EQU 1 
ENDC 

IFD INT 
INTE EQU 1 

ENDC 

IFD GFX 
GFXE EQU 1 
ENDC 



;MAKE SURE DOS IS THERE 



:MAKE SURE INTUITION IS THERE 



;MAKE SURE THE EQUATES GET INCLUDED IF MAIN SYMBOL DEFINED 



u 
u 

Li 
U 
U 
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IFD DEV 
DEVE EQU 1 
ENDC 

INCLUDE " INCLUDES ! SYSEQUATES . ASM" 

IFD DOSE 

INCLUDE "INCLUDES : DOSEQUATES . ASM" 

ENDC 

IFD GFXE 

INCLUDE " I NCLUDES : GFXEQU ATES . ASM " 

ENDC 

IFD INTE 

INCLUDE " INCLUDES : INTEQUATES . ASM" 

ENDC 

IFD DEVE 

INCLUDE " INCLUDES t DEVEQUATES . ASM" 

ENDC 

IFND JAM1 
JAM1 EQU 
ENDC 

INCLUDE "INCLUDESiMACROS.ASM" 

IFD WIN 

INCLUDE " INCLUDES iWINDOWS. ASM" 

ENDC 

IFD TXT 

INCLUDE "INCLUDES: TEXTS. ASM" 

ENDC 

IFD GAD 

INCLUDE "INCLUDEStGADGETS.ASM" 

ENDC 

IFD MAT 

INCLUDE "INCLUDES: MATH. ASM" 

ENDC 

IFD MEN 

INCLUDE "INCLUDES: MENUS. ASM" 

ENDC 

IFD REQ 

INCLUDE " INCLUDES :REQS. ASM" 

ENDC 

INCLUDE "INCLUDES:STARTUP.ASM" 

LIST 



Use EMACS to type in and save HEADER to the 
RAMIT/INCLUDES directory. Type the CLI command: 
DEV:RAMIT/EMACSDEV:RAMIT/INCLUDES/HEADER. 
Before typing in HEADER, you should read Chapter 10 for 
more complete instructions. 
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If you're working with the companion disk from COMPUTE! 
Publications, there's no need to create a working disk. The 
companion disk is already organized with a complete set of 
development files and an assembler program. You may wish 
to skip this chapter or quickly skim it for reference. Be sure to 
follow the instructions that accompany the companion disk. 

Organization 

Before getting underway with machine language program- 
ming, it's wise to organize a working disk with a convenient 
set of directories and files. The purpose of this section is to 
help you set up a working disk. 

You'll need three disks for this procedure: a new blank 
disk; the EXTRAS disk that comes with the 1.2 system 
Enhancer software, from Commodore; and the Macroassembler 
Development System disk, which can be purchased from your 
Amiga dealer. 

• Open a CLI in the Workbench environment to allow you to 
execute DOS commands, such as COPY and ASSIGN. 

• Use the Workbench Initialize Menu command to format a 
new blank disk in the external disk drive (DF1:) with the 
name DEV. This procedure prepares your blank disk to hold 
programs and files in the format required by the Amiga. New I j 
disks must be formatted before you use them. ^ — 

• In the CLI, type the commands: 

MAKEDIR DFlrRAMIT |_J 

MAKEDIR DF1.RAMIT/INCLUDES 

• Now, remove the DEV disk from drive DF1: and insert the ! j 
Metacomco disk. *- — ' 

• Type in these commands to move the assembler and linker 

into a ramdisk temporarily: j 
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DELETE RAM: ALL 

COPY DF1:C/ASSEM TO RAM:ASSEM 

COPY DF1:C/ALINK TO RAM:ALINK 

• Remove the Macroassembler Development System disk and 
insert the EXTRAS disk into DF1: 

• In order to move the MICROEMACS text editor from the 
Tools directory of the EXTRAS disk into the ramdisk, with a 
new name EMACS, type the command: 

COPY DFl:TOOLS/MICROEMACS TO RAM:EMACS 

• Remove the EXTRAS disk and insert the DEV disk in drive 
DF1:. 

• Type in the commands: 

COPY RAM: TO DF1:RAMIT ALL 
DELETE RAM: ALL 

After this sequence of steps, the RAMIT directory on DEV 
contains the ASSEM, ALINK, and EMACS files, and the 
ramdisk is empty again. 

In order to complete the construction of a working devel- 
opment disk (DEV), use the MICROEMACS program to type 
in the listings in this book and save them to the DEV disk. 

• Use EMACS to type in and save the SYSEQUATES.ASM file 
to the RAMIT/INCLUDES directory. Type the CLI 
command: 

DEV:RAMIT/EMACS 
DEV:RAMIT/INCLUDES/SYSEQUATES.ASM 

This will run the EMACS program placed on the DEV 
disk earlier, and it will start by creating a new file named 
SYSEQUATES.ASM in the RAMIT/INCLUDES/ directory on 
the DEV disk. 

|— I • Type in the SYSEQUATES.ASM file found at the end of this 
I chapter. While you're typing in the file, it's wise to use the 
SAVE option from the EMACS menu periodically. When 

n you're finished typing in the file, use the SAVE-EXIT option 
in the EMACS menu. 

You should now have a complete SYSEQUATES.ASM 
file on your DEV disk/located in the RAMIT/INCLUDES 
directory. 

• Use EMACS to type in the following additional files, which 
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are listed at the end of this chapter: 

SYSEQUATES.ASM (Save as file DEV:RAMIT/INCLUDES/SYSEQUATES.ASM) 
DOSEQUATES.ASM (Save as file DEV:RAMIT/INCLUDES/DOSEQUATES.ASM) 
MACROS.ASM (Save as file DEV:RAMIT/INCLUDES/MACROS.ASM) 

Now the DEV disk is ready for use. It has a set of in- 
clude files in its RAMIT/INCLUDES directory, and it also 
has the ASSEMBLER, LINKER, EMACS, and HEADER files 
in its RAMIT directory. These files are all you need to get 
started with some fairly sophisticated Amiga machine lan- 
guage programming. 
• Make a copy of the DEV disk using the DISKCOPY com- 
mand (in the CLI) or the WorkBench DUPLICATE menu 
selection. 

The equate files presented here are short versions that 
contain the necessary symbol definitions required for programs 
in this book only. They are short enough to type in. More 
complete versions of these files are on the companion disk, or 
you can add to these files by examining the includes files on 
the Metacomco Assembly Development disk, or by copying in 
the relevant information from the Amiga kernal reference 
manuals. 

The longer versions of the equate files may be too large 
for a 150K workspace, which is a concern if you have a 512K 
Amiga. If you have expansion RAM, you may wish to use the 
longer versions available on the companion disk. If you do so, 
you should also pay attention to the 15 OK workspace used in 
most of the examples in this book. A larger workspace can be 
arranged for the Metacomco assembler, if you have enough 
memory in your Amiga. Just change the -c wl 50000 option in 
the assembler command line to accomodate large files (for in- j I 
stance, -c W300000 to accomodate 300K). 

There are two additional equate files that you may find 
useful at another time, but which you can leave alone for now. I j 
These are GFXEQUATES.ASM and INTEQUATES.ASM. They ' — ' 
contain the required symbol definitions for programs that use 
Intuition features (such as windows and menus) and the ( j 

Graphics functions (RECTFILL, AREADRAW, and others). ' — ' 

These are discussed in later chapters. There are also a number 
of additional include files used by some of the programs pre- j I 
sented later in the book (WINDOWS.ASM, GADGETS.ASM, ' — ' 

MATH.ASM, and so on). 
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As these additional include files are introduced in later 
chapters, you'll need to type them in and save them in the 
RAMIT/INCLUDES directory, with the procedure outlined 
above. 



Because naming conventions and methods differ 
slightly, the programs in this book can only be assembled 
using the files in this book. Likewise, existing source code 
programs written for the Metacomco include files can only 
be assembled using their files. 



Listing 10-1. SYSEQUATES.ASM 

.*•*•**** SYSEQUATES.ASM 

! COPYRIGHT 1988 COMPUTE! Publications 

,-03/24/87 

.*** SYSTEM (EXEC) LIBRARY ROUTINE OFFSETS (PARTIAL LIST FROM AMIGA. LIB) 



LVO.ALLOCMEM 




EQU SFFFFFF3A 


LVO.CLOSELIBRARY 


EUU 


5FFFFFE62 


LVO.FINDTASK 




EQU 5FFFFFEDA 


LVO. FORBID 


EQU 


SFFFFFF7C 


LVO.FREEMEM 




EQU 5FFFFFF2E 


LVO.GETCC 


EQU 


SFFFFFDF0 


LVO.GETMSG 


EQU 


5FFFFFE8C 


LVO.OPENLIBRARY 


EQU 


SFFFFFDD8 


LVO. PERMIT 


EQU 


SFFFFFF76 


LVO.REPLYMSG 




EQU SFFFFFE86 


LVO. WAIT 


EQU 


5FFFFFEC2 


LVO.WAITIO 


EQU 


SFFFFFE26 


LVO.WAITPORT 




EQU 5FFFFFE80 


.*** MEMORY ALLOCATION CONSTANTS 


MEMF CHIP EQU S2 






MEMF CLEAR EQU $10000 




MEMF FAST EQU $4 






MEMF LARGEST 


EQU 


$20000 


MEMF PUBLIC 


EQU 


$1 



SYSBASE EQU $4 
ABSEXECBASE EQU $4 



Listing 10-2. DOSEQUATES.ASM 

.******•• DOSEQUATES.ASM 

; COPYRIGHT 1988 COMPUTE I Publications 

;03/24/87 

;*** DOS LIBRARY ROUTINE OFFSETS (PARTIAL LIST FROM AMIGA. LIB) 
FH.TYPE EQU $8 



LVO. CLOSE 
LVO.CURRENTDIR 
LVO.PARENTDIR 
LVO. DELAY 
LVO. INPUT 
LVO. OPEN 
LVO. OUTPUT 



EQU SFFFFFFDC 

EQU SFFFFFF82 
EQU 5FFFFFF2E 

EQU SFFFFFF3A 

EQU $FFFFFFCA 

EQU $FFFFFFE2 

EQU 5FFFFFFC4 



103 



Chapter 10 



U 
U 



LVO.READ 


EQU $FF1 


?FFFI 


)6 


LVO. WRITE 


EQU SFFFFFFD0 


LVO . EXECUTE 




EQU 


$FFFFFF22 


LVO. LOCK 


EQU 5FFFFFFAC 


MODE NEWFILE 




EQU 


$3EE 


MODE OLDFILE 




EQU 


S3ED 


ACCESS READ 


EQU 


-2 




SHARED LOCK 


EQU -2 






EXCLUSIVE LOCK 




EQU 


-1 


ACCESS_WRITE 




EQU 


-1 


.».* PROCESS STRUCTURE OFFSETS 




PROC.CLI 


EQU $AC 






PROC . CONSOLETASK 


EQU $A4 






PROC.MSGPORT 




EQU 


$5C 


PROC.STACKBASE 




EQU 


$90 


PROC.STACKSIZE 




EQU 


$84 


PROC. TASK 


EQU $0 






PROC.TASKNUM 




EQU 


$8C 


PROC.WINDOWPTR 




EQU 


?B8 


TICKS PERSECOND 




EQU 


50 


.******** SFXEOUATES.ASH 






; 03/24/87 








;*** GRAPHICS CONSTANTS 






COMPLEMENT EQU $2 








EXTRA HALFBRITE EQU 


$80 






HAM 


EQU $800 




HIRES 


EQU $3000 




INVERSVID EQU $4 








JAM! 


EQU $0 






JAM2 


EQU $1 






LACE 


EQU $4 







u 



.*** GRAPHICS LIBRARY ROUTINE OFFSETS (PARTIAL LIST FROM AMIGA. LIB) 

LVO.BLTTEMPLATE EQU $FFFFFFDC 
LVO.CLEAREOL EQU $FFFFFFD6 
LVO.CLEARREGION EQU $FFFFFDF0 
LVO . CLEARSCREEN EQU $FFFFFFD0 
LVO. DRAW EQU $FFFFFF0A 
LVO. FLOOD EQU SFFFFFEB6 
LVO.GETRGB4 EQU SFFFFFDBA 
LVO.LOADRGB4 EQU SFFFFFF40 
LVO. MOVE EQU $FFFFFF10 
LVO.POLYDRAW EQU $FFFFFEB0 
LVO.READPIXEL EQU $FFFFFEC2 
LVO.RECTFILL EQU $FFFFFECE 
LVO.SETAPEN EQU $FFFFFEAA 
LVO.SETBP.EN EQU SFFFFFEA4 
LVO.SETDRMD EQU $FFFFFE9E 
LVO.SETRGB4 EQU $FFFFFEE0 
LVO.WRITEPIXEL EQU $FFFFFEBC 

,*** A COUPLE OF RASTPORT STRUCTURE OFFSETS 

RP.FGPEN EQU $19 

RP.BGPEN EQU $1A 
RP.OPEN EQU $IB 

RP.DRAWMODE EQU $1C 

.»** A COUPLE OF VIEWPORT STRUCTURE OFFSETS 



u 

u 
u 
u 
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Listing 10-3. MACROS.ASM 

..«..**». *,**.»*..*,,.,•••. .,,.,« MACROS.ASM BY D. WOLF 
;COPYRIGHT 1987 BY COMPUTEI BOOKS 
; 38/04/37 

;*** SYSTEM MACRO DEFINITIONS *** 

BVENPC MACRO ;USED TO WORD-ALIGN THE PROGRAM COUNTER I 
DS.W 
ENDM 

ZERO MACRO 
MOVEQ #0,\1 
ENDM 

ZERA MACRO 
SUBA.L \1,\1 
ENDM 

PUSHREG MACRO ; REGISTERS 
MOVEM.L \1,-(SP) 
ENDM 

PUSHALL MACRO 
PUSHREG D0-D7/A0-A6 
ENDM 

PULLREG MACRO ; REGISTERS 
MOVEM.L (SP)+,\1 
ENDM 

PULLALL MACRO 
PULLREG D0-D7/A0-A6 
ENDM 

LIBCALL MACRO ; LIBRARY, ROUTINE 
MOVE.L \1,A6 
JSR LVO.\2(A6) 
ENDM 

SYSLIB MACRO ; ROUTINE 
LIBCALL SYSBASE,\1 
ENDM 

DOSLIB MACRO {ROUTINE 
LIBCALL _DOSBASE,\l 

ENDM 

GFXLIB MACRO ;ROUTINE[ ,*RASTPORT] 
IFNC '\2' , ' ' 
MOVE.L \2,A1 
ENDC 

LIBCALL _GFXBASE,\1 
ENDM 

INTLIB MACRO ! ROUTINE 
LIBCALL INTBASE,\1 

ENDM ~ 

MATHLIB MACRO ; ROUTINE 
LIBCALL _MATHBASE,\1 
ENDM 

TRANSLIB MACRO ; ROUTINE 
LIBCALL _MATHTRANSBASE,\1 
ENDM 

ICONLIB MACRO ; ROUTINE 
LIBCALL _ICONBASE,\l 
ENDM 

JUST MACRO ; ROUTINE 
JSR LVO.\l(A6) 
ENDM 
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EMERGENCY MACRO 7 ERROR CODE (D0) POTS ERROR IN D0 AND MAKES FAST EXIT I 
MOVE.L #\1,D0 
JMP _ERROR 
ENDM 

ALLOCPUBMEM MACRO :SIZE 
MOVE.L \1,D0 

MOVE.L #MEMP PUBLIC1MEMF CLEAR, Dl 
SYSLIB ALLOCMEM 
ENDM 

FREEMEM MACRO ; ADDRESS, SIZE 
MOVE.L \1,A1 
MOVE.L \2,D0 

SYSLIB FREEMEM 
ENDM 

;*** DOS MACRO DEFINITIONS *** 

DOSREAD MACRO :*FILEHANDLE (D1),*BUFF (D2),LEN (D3) 
MOVE.L \1,DI 
MOVE.L \2,D2 
MOVE.L \3,D3 
DOSLIB READ 
ENDM 

DOSPRINT MACRO ;*FILEHANDLE (DI),*BUFF (D2), [LEN (D3)D 
PUSHREG D1-D3/A0-A1 
MOVE.L \I,D1 
MOVE.L \2,D2 
IFC "\3', ' ' 

BSR DOSTEXTLEN ;IF NO LENGTH SPECIFIED, GO CALCULATE IT 
ENDC 

IFNC ' \3 ' , " 
MOVE.L \3,D3 
ENDC 

DOSLIB WRITE 
PULLREG D1-D3/A0-A1 
ENDM 

IFD DOS 

DOSTEXTLEN ; CALCULATES LENGTH OF NULL-TERMINATED STRING INTO D3 FOR DOS 

MOVE.L D2.A0 
15 

TST.B (A0)+ 

BNE.S 1$ 

MOVE.L A0.D3 

SUB.L D2.D3 

SUBQ.L #1,D3 

RTS 

ENDC 

;**** INTUITION MACRO DEFINITIONS *** 

REMEMBERCHIPMEM MACRO !*REMEMBERKEY, SIZE (A0.D0) 
LEA \l,AO 
MOVEQ.L #0,D0 
MOVE \2,D0 

MOVE.L #MEMF_CLEAR1MEMF_CHIP, Dl 
INTLIB ALLOCREMEMBER 
IFNC '\3' ,' ' 
TST.L D0 
BEQ \3 
ENDC 
ENDM 

REMEMBERPUBMEM MACRO ;*REMEMBERKEY, SIZE (A0,D0) 
LEA \1,A0 
MOVEQ.L #0,D0 
MOVE \2,D0 

MOVE . L #MEMF_CLEAR1 MEMF_PUBLIC , Dl 
INTLIB ALLOCREMEMBER 
IFNC '\3'," 
TST.L D0 
BEQ \3 
ENDC 
ENDM 



u 
u 
u 
u 
u 
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.»** GRAPHICS MACRO DEFINITIONS 

GFXPOINT MACRO ;[*X,*Y] 
IFNC ' \1 ' , ' ' 
MOVE.W \1,D0 
MOVE.W \2,D1 
ENDC 

EXT.L D0 
EXT.L DI 
ENDM 

GFXPUSH MACRO 
PUSHREG D0-DI/A0-A1 
ENDM 

GFXPULL MACRO 
PULLREG D0-D1/A0-A1 
ENDM 

LOADRGB MACRO 
GFXPUSH 
MOVEA.L \1,A0 
LEA \2,A1 
MOVEQ #\3,D0 
GFXLIB L0ADRGB4 
GFXPULL 
ENDM 

SETOPEN MACRO 
IFNC ' \2 ■ , " 
MOVE.W \2,D0 
ENDC 

MOVE.L \1,A1 
MOVE.B D0,RP.OPEN(A1) 
ENDM 

SETAPEN MACRO 
GFXPUSH 
IFNC , \2'. " 
MOVE.W \2,D0 
ENDC 

GFXLIB SETAPEN, \1 
GFXPULL 
ENDM 

SETBPEN MACRO 
GFXPUSH 
IFNC ' \2 ' , ' • 
MOVE.W \2,D0 
ENDC 

GFXLIB SETBPEN, \1 
GFXPULL 
ENDM 



;IF FIRST ARGUMENT *NOT* A 'BLANK' 
;PUT X,Y INTO REGISTER WORDS 
fONLY IF NECESSARY 

.•EXTEND REGISTERS TO LONG WORDS 

ITHIS PUTS HIGHEST BIT OF 'LOW' WORD INTO 

;ALL BITS OF 'HIGH' WORD IN SAME REGISTER 

,-PUSH 4 MAIN REGISTERS 



;PULL 4 MAIN REGISTERS 



. 'VIEWPORT, COLORMAP, COUNT 

;GET ADDRESS OF VIEWPORT INTO A0 

.•POINTER TO LABELLED COLORVALUE LIST 

;HOW MANY COLOR REGISTERS TO FILL 

;PUT COLORVALUES INTO USE FOR THIS VIEWPORT 



; *RASTPORT[ , *COLOR] 
;SET OUTLINE PEN COLOR t 



;PTR TO RASTPORT INTO Al 

;THERE IS NO LIBRARY FUNCTION FOR THISIII 



; *RASTPORT[ , *COLOR] 

;SET FOREGROUND DRAWING PEN FOR JAM1 



; *RASTPORT[ , *COLOR] 

.-SET BACKGROUND DRAWING PEN FOR JAM2 



SETDRMD MACRO ; 
GFXPUSH 
IFNC ' \2 ' , ' ' 
MOVE.W \2,D0 
ENDC 

GFXLIB SETDRMD, \1 
GFXPULL 
ENDM 



•RASTPORT, MODE (JAM1, JAM2, COMPLEMENT) 



FILLWIN MACRO 
ZERO D0 
MOVEA.L \1,A0 
MOVE.L WW.RPORT(A0),RP 
IFNC '\2' , ' ' 
MOVE.W #\2,D0 
ENDC 

SETAPEN RP 

MOVE.W WW.WIDTH(A0),D2 
SUBI.W #4,D2 
MOVE.W WW.HEIGHT(A0),D3 
SUBI.W #2,D3 
MOVE.W #2,D0 
MOVE.W #10, Dl 
RECTFILL RP 
ENDM 



WINDOW, [COLOR REG #] FILLS A WINDOW WITH A SOLID COLOR 
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RECTFILL MACRO 
PUSHRE6 D0-D3 
MOVEA.L \1,A1 
IFNC ' \2'," 
MOVE.W \2,D0 
MOVE.W \3,D1 
MOVE.W \4,D2 - 
MOVE.W \5,D3 
ENDC 

D0 

Dl 

D2 

D3 

GFXLIB RECTFILL 
PULLREG D0-D3 
ENDM 



EXT.L 
EXT.L 
EXT.L 
EXT.L 



; *RASTPORT[ , *X1 , *Y1 , *X2 , *Y2] 

•POINTER TO RASTPORT TO DRAW INTO IN Al 

•IF SECOND ARGUMENT IS *NOT* A 'BLANK' 

;THEN MACRO CALL SHOULD CONTAIN ALL ARGUMENTS I 

;MOVE X,Y COORDINATES TO REGS. 

; EITHER AS IMMEDIATE DATA (# IN MACRO CALL) 

;OR FROM LABELLED LOCATIONS (LABELS ARE THE ARGUMENTS THEN) 

;IF DATA WERE IN MEMORY, NEED TO EXTEND TO LONG WORD 
;IF THEY WERE ALWAYS # IMMEDIATE DATA, THESE EXT.L 'S 
;WOULDN'T BE NEEDED - WE COULD USE MOVE.L's (ABOVE) INSTEAD. 

;CALL GRAPHICS ROUTINE FOR THIS RASTPORT 'DRAW' 



u 
u 
u 

u 



DRAWPOINT MACRO ;*RASTPORT[ ,*X,*Y] 
GFXPUSH 
GFXPOINT \2,\3 
GFXLIB WRITEPIXEL,\1 
GFXPULL 
ENDM 



;SET THE X,Y COORDINATES IN REGISTERS 
;NOW DO THE WRITEPIXEL IN THIS RASTPORT 



READPOINT MACRO 
PUSHREG Dl 
GFXPOINT \2,\3 
GFXLIB READPIXEL.U 
PULLREG Dl 
ENDM 

DRAWLINE MACRO 
PUSHREG D0-D3 
MOVE.L \1,A1 
IFNC '\2'," 
MOVE.W \2,D0 
MOVE.W \3,D1 
MOVE.W \4,D2 
MOVE.W \5,D3 
ENDC 

BSR _DRAWLINE 
PULLREG D0-D3 
ENDM 

IFD GFX 

_DRAWLINE 
PUSHREG D0-D1 
PUSHREG Al 
EXT.L D0 
EXT.L Dl 
GFXLIB MOVE 
MOVE.W D2.D0 
MOVE.W D3.D1 
EXT.L D0 
EXT.L Dl 
PULLREG Al 
JUST DRAW 
PULLREG D0-D1 
RTS 



ENDC 

;*•* FLOATING POINT MACROS *** 

RMATH MACRO ; 
MOVE.L _MATHBASE,A6 
ENDM 

TMATH MACRO ; 
MOVE.L _MATHTRANSBASE,A6 
ENDM 

FLOAT MACRO; 
MOVE.W \1,D0 
EXT.L D0 
JUST SPFlt 
MOVE.L D0,\2 
ENDM 



; *RASTPORT[ , *X, *Y] 

;SET THE X,Y COORDINATES IN REGISTERS 
fNOW DO THE READPIXEL FROM THIS RASTPORT 



; * RASTPORTt , *X1 , *Y1 , *X2 , * Y2 ] 

; SIMILAR TO THE RECTFILL FORMAT, 



; ENTER WITH RASTPORT IN Al, POINTS IN D0,D1,D2,D3 



u 
u 
u 
u 
u 
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Comparing Equate Files To Amiga Include Files 

The programs in this book use naming and symbol definition 
conventions different from those in the A files on the 
Metacomco disk. 

• The files in this book use all capital letters while the 
Metacomco files use combinations of upper- and lowercase 
letters: 

Example: This book ALLOCMEM 
Metacomco AllocMem 

• Library routines are also in uppercase letters in this book, as 
opposed to Metacomco's use of mixed upper- and lowercase 
letters. 

Example: This book D/O.xxxxxxx 

Metacomco -XXOxxxxxxx 

Example: This book LVO.OPENLIBRARY 

Metacomco _LVOOpenLibrary 

• You 11 sometimes find shortened names for structures and 
structure offsets in this book, to save typing. 

Example: This book WW.RPORT 
Metacomco Window.RastPort 

• Library routine offsets in this book are defined as constants 
in equate files. The equate files are included during assembly 
and no linkage with external files is required. Metacomco de- 
fines the library routine offsets in a separate link file called 
AMIGA.LIB. The programmer must declare most library 
routines as external references using the XREF and XDEF 
directives, and later link the program with AMIGA.LIB. 

Example: This book LVO.OPENLIBRARY EQU $FFFFFDD8 
Metacomco XREF _LVOOpenLibrary 

• Programs in this book define structure offsets as constants in 
equate files, also. 

Example: WW.LEFTEDGE EQU 

Metacomco uses a very different method of defining struc- 
tures. A complete explanation of that method is beyond the 
scope of this book. Using Metacomco's method, the name of 
each field offset (in this case, Window.LeftEdge is the 
Metacomco equivalent name) is assigned a numeric value dur- 
ing assembly. This method is very flexible and clever, but it 



109 



Chapter 10 



U 
U 

requires that the programmer have a detailed understanding of j 
the macros in Metacomco's Types.i include file. Those macros ' — ' 
allow machine language programmers to mimic the C lan- 
guage style of structure definition and field naming. This ap- | I 
proach has advantages for advanced programmers. ' — ' 

This summary comparison of the programming system 
used in this book and the approach used in the Metacomco in- 
clude files points up advantages and disadvantages of each: ' — ' 

• Because a complete exposition on each of the more than 70 
Metacomco include files would have been impossible within 
the scope of this book, four equate files were substituted for 
them. 

• Because typing in a complete set of include files for the 
Amiga would have been a formidable job, the files for this 
book were shortened by limiting them to the library func- 
tions used here. 

• Because the files in this book have explicit, constant defini- 
tions, you'll probably find them easier to understand and use 
than the Metacomco include files. 

• You can convert from one style to the other fairly easily by 
referring to this section of the book. It doesn't matter which 
assembler is used (ASM68010 on the companion disk, or 
ASSEM on the Metacomco disk). What is important is that 
the include files match the program code names and 
symbols. 

• Because the files in this book are shorter (50K versus 300K), 
a 512K Amiga should have plenty of room for them. Shorter 
files also reduce the time required for assembly. 

• The HEADER file does all the work of deciding which equate 

files are needed during assembly. Its not always clear which , , 

of the 70-odd include files are required when using the | j 

Metacomco system. 



Extending the Equate Files 

To minimize the work of typing in the equate files 
(SYSEQUATES.ASM, and so on) the library offset definitions 
for all functions were not included. If you wish to write pro- 
grams using functions that aren't defined in these files, you'll 
have to provide their library offset definitions yourself. 

For example, say you want to use the BLITCLEAR function 
in the Graphics Library. If you examine the GFXEQUATES.ASM 
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file, you'll find there's no mention of the BLITCLEAR func- 
tion. You must add a line to the equate file that looks like: 

LVO.BLITCLEAR EQU $FFFFFxxx 

To find the information to plug into the empty bytes repre- 
sented by lowercase xs in $FFFFFxxx, look in the Amiga ROM 
Kernel ManuahExec. In Appendix D of that volume, there is a 
long list of the numbers you need. On Page D-6, you'll find the 
number for the BlitClear function, namely FFFFFED4. (It's 
shown as 0xfed4, the C programmer's way of writing $FFFFFED4.) 

Now you can add the following BLITCLEAR definition to 
the equate file: 

LVO.BLITCLEAR EQU SFFFFFED4 

Using EMACS, it's easy to add the one line and resave the 
GFXEQUATES.ASM file with the modification. 

Later, when you're programming and need the 
BLITCLEAR, you can simply enter: 

GFXLIB BLITCLEAR ; (USING APPROPRIATE REGISTER PARAMETERS) 

and the assembler will have no trouble making the connection 
to the new version of the equate file. 

If you don't happen to have the "Exec" manual, but 
you do have the Metacomco disk, you can also type out the 
AMIGA.LIB file and read the numerical versions of the 
-DJOxxxxxxx offsets there. 

The equate files in this book are short enough to type in, 
and long enough to cover many Amiga library functions that 
give your programs most of the fundamentals (windows, 
menus, and so on). They're simple enough to expand with ad- 
ditional Amiga library functions. 

If you need to add definitions of more structures to these 
files, please compare how they're specified in the equate files 
as opposed to the Metacomco include files. The numerical defi- 
nitions of each of the offsets was established by counting from 
the beginning of the structure. Where Metacomco says a field is 
a BYTE, add one to the previous field's offset value. Here is a 
list of the equivalents between Metacomco's structure defini- 
tions and the definitions used in this book: 
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Listing 


Value 


Meaning 


BYTE 
UBYTE 


One byte 
One byte 


Signed byte 
Unsigned byte 


u 


SHORT 
USHORT 


Two bytes 
Two bytes 


Signed word 
Unsigned word 


LONG 

ULONG 


Four bytes 
Four bytes 


Signed long word 
Unsigned long word 


u 


APTR 
STRUCT 


Four bytes 
Four bytes 


Address pointer 

Pointer to another structure 





This example is based on Metacomco's NewWindow Structure 
Definition listed in the Amiga Intuition Reference Manual, Ap- 
pendix B, page 12: 



NewWindow 






USHORT 
USHORT 
USHORT 


LeftEdge 
TopEdge 
Width 






Means: (using our 


notation in the equate files) 


NW.LEFTEDGE 

NW.TOPEDGE 

NW.WIDTH 


EQU 
EQU 

EQU 


$0 

$2 
$4 


; 1 WORD FROM THE TOP OF THE STRUCTURE 
; 2 WORDS FROM THE TOP OF THE 
; STRUCTURE 
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r| Amiga Libraries 

j~""| The Amiga is a multitasking computer. All of the programs in 
this book are intended to participate in the Amiga's multi- 
tasking environment. They utilize the wide range of the 
Amiga's resources. 

Intuition 

Intuition is an internal library of programs used to manipulate 
windows, mouse, menus, and so on in the familiar Amiga user 
interface. Working with Intuition requires that you write your 
programs to conform to certain minimum standards of mem- 
ory use and error checking. Here are a couple of things to 
keep in mind when designing Amiga programs: 

• Your programs should be written in relocatable code. 

• A program should free system resources (memory, libraries, 
devices, and so on) when finished with them. 

• Programs should be polite to other programs running 
simultaneously. 

• A program must begin and end its operations gracefully. 

Relocatable code. The first requirement means you 
usually should not refer to specific memory addresses in pro- 
grams. Programmers cannot be sure where their programs will 
reside when loaded. A programmer can't assume that a mem- 
ory array resides at a particular address, either. It is also dan- 
gerous to write self-modifying code. Well-designed source 
code is written using labels and symbols, allowing the assem- 
bler and linker to assign relocatable addresses. 

The AmigaDOS loader that brings a program into mem- 
ory modifies it according to the address where it is loaded. In 
other words, a program is a template until it's loaded into 
memory. The file containing an executable program also con- 
tains the information required by the loader to perform a fill- 
in-the-blank process at load time. The disk file is actually 
called a load module. 

Sometimes, you need to refer to some of the fixed hard- 
ware device addresses, like the serial ports, and others that are 
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documented in the Amiga Hardware Reference Manual. Since I I 

these areas are never used as program storage or data storage, ^ 
using their specific addresses is legal. Only the user RAM is 
jumbled up with programs and list structures by the operating j 
system. 

Other requirements. The other demands Intuition places 
on the programmer are that programs should have a special j j 

startup section, a main section for instructions, and a special ^ 

ending section. The startup code sets up your access to system 
resources and looks up some needed addresses; then, your 
MAIN section operates using them; and finally, the ending 
section frees the resources claimed by the startup section and 
returns to the Workbench or CLI. 

A STARTUP.ASM program is provided with this book 
(see Chapter 14). It gives complete startup and ending sec- 
tions where you can sandwich your own code. When this 
STARTUP.ASM program is used, it's always easy to create a 
new program. Simply write a file named source, making sure 
one of its first lines is: 

INCLUDE STARTUP.ASM 

Most programs in this book utilize STARTUP.ASM to sim- 
plify and unify the coding/assembly/link sequence. It opens 
libraries and sets up the environment for the application, and 
then closes libraries and performs the necessary graceful exit. 
There will be a closer look at STARTUP.ASM after we examine 
the concepts of memory allocation and the Amiga's libraries. 

Amiga Libraries 

The Amiga provides hundreds of kilobytes of functions for use 

in applications programs. If you want to draw a circle on the j i 

screen, call a subroutine in the Graphics library. If you want to 

print text in a window, call a subroutine in the Intuition - - 

library. J 

To maintain software compatibility from release to release, 
libraries are conveniently organized for programmers. The 
Amiga libraries are organized as jump tables. A jump table is a I I 
list of addresses of the actual functions. Table 11-1 is a list of 
the libraries in the Amiga's ROM. The programmer opens a li- 
brary by calling OPENLIBRARY. OPENLIBRARY returns the I I 
address of the jump table for the specified library. An appar- 
ent Catch-22 is that library access is controlled by the Exec li- 
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brary (that's where OPENLIBRARY and CLOSELIBRARY are). 
Exec is the one library that doesn't need opening. The base 
address of the Exec library's jump table is always located at 
memory location 4 in the Amiga's RAM. This one location is 
the only permanently assigned memory location for Amiga 
software. By making this one number a permanent resident of 
location 4, the rest of the system's libraries become accessible 
through Exec's OPENLIBRARY call. 

Once the base address of a library's jump table is found, 
the address of each of that library's functions is lined up for 
easy access, relative to that base address. (See Figure 11-1.) To 
use a function whose address is in the library, a Jump to Sub- 
Routine 0SR) is made to an offset from the jump table base 
address in A6. Examples of opening a library are shown in 
Listing 11-1. They demonstrate how to call the Exec library's 
OPENLIBRARY function and check for errors after its use. 
They also demonstrate that, in general, the Exec library func- 
tions require that their parameters be made available in ad- 
dress register Al. 

Figure 11-1. Amiga Library General Structure 

A typical Amiga library is organized into a jump table so that the actual location 
of the functions becomes irrelevant. 

Library of Routines 



HIGH 



















m 





MEMORY 1 



6 7 8 



IB 



MEMORY 



n 
n 
n 
n 
n 





PTR TO ROUTINE 


2 


PTR TO ROUTINE 


3 


PTR TO ROUTINE 1 


PTR TO ROUTINE 


7 


Reserved 


Extra 

Library 
Infornation 



Library 

Junp 

Table 



BASE -28 
BASE-SE 
BASE- 16 
BASE-1Q 



Pointers to Routines 
in the Library 



"OPEH LIBRARY- 



GET BASE ADDRESS 



Library 

'Base Address' 



A Library Junp Table 



USE ROUTINE »7— >fMOVE.L BASE ADDRESS, 

A6 

(JSR-ie CA6) 

OR: l~Routine? EQU-10 

J MOUE.L BASE ADDRESS, 
1 «6 






JSR R0UTINE7CA6) 
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Table 11-1. Amiga ROM Kernel Libraries 

Library 

Clist 
DOS 
Exec 

Graphics 

Icon 

Intuition 

Layers 

MathFFP 

MathlEEDoubBas 

MathTrans 

Potgo 
Timer 

Translator 



Contents 

Character string functions for the clipboard 
AmigaDOS, I/O, file handling 
Library access, memory allocation, message ports, 
and so on 

Sprites, color maps, rectangular fills, and so on 
Workbench icon functions 
User Interface functions (menus, gadgets, win- 
dows, and so on) 

Graphic layering functions (usually used only by 
system) 

32-bit fast floating-point math functions 
(Arithmetic) 

64-bit IEEE floating-point math functions 
(Arithmetic) 

32-bit Transcendental math functions (sin, cosine, 
and so on) 

Pot bits functions, game port functions 
Functions for reading, setting the Amiga timer 
Translator functions for speech synthesizer output 



Listing 11-1. Programming Examples: Opening a Library 



MOVEQ 
MOVEA.L 

LEA 

JSR 

TST.L 
BEQ 



#0,D0 
4,A6 

DOSNAME.A0 

LV0.0PENLIBRARY(A6) 

DO 
ERROR-DOSLIB 



MOVE.L D0_DOSBASE 



DOSNAME DC.B 'DOS.LIBRARY',0 
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TO OPEN THE DOS LIBRARY ■ 

NO PARTICULAR VERSION 

EXEC LIBRARY JUMP TABLE 

ADDRESS INTO A6 

PUT POINTER TO NAME OF 

LIBRARY INTO AO 

USE THE EXEC OPENLIBRARY 

FUNCTION 

DID THE OPEN SUCCEED? 

NO, DO CAME BACK EMPTY, SO 

HANDLE THE ERROR 

YES, DO HAS THE ADDRESS OF 

THE DOS LIBRARY 
SM. THAT NUMBER FOR LATER 
USE 

MORE PROGRAM CODE GOES 

HERE 

AND THE FOLLOWING MUST BE 

PLACED IN YOUR DATA 

DECLARATIONS 

; LABELLED TEXT OF OFFICIAL 
; LIBRARY NAME 



u 

u 
u 

u 
u 



L-J 
U 
U 
U 
D 
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-DOSBASE DCL 





; ROOM FOR STORING THE 








; LIBRARY'S 'BASE' 


n 


1 




TO OPEN THE INTUITION 






LIBRARY - 


■HA 


MOVEQ 


#0,D0 


; DON'T SPECIFY ANY VERSION 
; OF LIBRARY 


n 


MOVEA.L 


4.A6 




LEA 


INTNAME,AO 






JSR 


LV0.0PENLIBRARY(A6) 






TST.L 


DO 


; REMEMBER TO CHECK FOR AN 
; ERROR 




BEQ 


ERROR-JNTLIB 






MOVE.L 


DO,_INTBASE 


; NO ERROR OCCURRED, DO HAS 



INTNAME DC.B 
-INTBASE DCL 



n 
n 
n 



MOVEQ.L 

MOVEA.L 

LEA 

JSR 

TST.L 

BEQ 

MOVE.L 

MOVE.L 

MOVE.L 
MOVE.L 



'INTUITION.LIBRARY',0 



#0,D0 

4.A6 

MATHNAME.AO 

LVO.OPENLIBRARY(A6) 

DO 

ERROR_MATHLIB 

DO,_MATHBASE 

D0.A6 

VARIABLE1,D0 
VARIABLE2.D1 



; ADDRESS 

MORE OF YOUR PROGRAM GOES 
HERE 

IN YOUR CODE'S 'DATA DEC- 
LARATIONS SECTION' ARE: 



OPENING OTHER LIBRARIES FOL- 
LOWS THIS FORMAT PRECISELY 
THERE MUST BE A LABELED LO- 
CATION FOR THE TEXT OF THE 
LIBRARY NAME 

THERE USUALLY SHOULD BE A 
LABELLED LOCATION FOR THE 
LIBRARY BASE 
WHICH COMES BACK IN DO 
AFTER A SUCCESSFUL CALL TO 
'OPENLIBRARY' 

TO OPEN AND USE A LIBRARY 
FUNCTION - EXAMPLE OF USING 
THE 'MATHLIB' 

TO ADD TOGETHER TWO 'FLOAT- 
ING POINT' NUMBERS 



SAVE LIBRARY BASE ADDRESS 
MOVE IT INTO A6 TO USE THE 
LIBRARY FUNCTIONS 
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MORE OF YOUR PROGRAM GOES 

HERE 

AND LATER, SOMEWHERE IN 

YOUR DATA DECLARATIONS 



MATHNAME DC.B 'MATHFFP.LIBRARY' 
-MATHBASE DC.L 



u 
u 



JSR LVO.SPADD(A6) ; DOES FLOATING POINT ADDI- i j 

; TION OF THE TWO 
NUMBERS IN DO AND Dl 

MOVE.L DO.SUMOF ; SUM OF THE NUMBERS COMES 

; BACK IN DO 
WE CHOSE TO SA/E IT IN 
'SUMOF' 



u 



Parameter passing. If you review the code examples that 
demonstrate the OPENLIBRARY function, you'll notice that 
certain information must be placed in registers before the 
function can be called. Those parameters are required by 
OPENLIBRARY to do its job. 

This is typical of Amiga library calls. The calling program 
sets up some required data in registers and then makes the 
call. Some calls also require a preexisting table of data (called 
a structure) prior to the call. Structures will be discussed in 
greater detail below. 

Libraries as system resources. Libraries are system re- 
sources. As mentioned above, any system resources used by 
your program must later be returned to the system. That 
means that libraries opened at the beginning of the program 
should be closed at the end, or when the program is finished 
using them. 

The Amiga's operating system must keep track of a library 
as long as it is open. If you have libraries open unnecessarily, j | 

you're wasting both memory space and processor time. Having L~-l 
your program open a library also places some restrictions on 
what the Amiga can do with that library internally. Usually, | 

the Amiga operating system is free to move whole libraries —— J 

anywhere in memory it finds convenient. But once a library is 
opened, the operating system knows it must not move the 
library. 

Therefore, in Listing 11-1, each library is individually 
opened and closed by name. The CLOSELIBRARY function is 
part of the Exec library, whose base address is always in mem- 
ory location 4. Since the Exec library is always open, you can 



U 
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always use the CLOSELIBRARY function to close any other li- 
brary except the Exec library. Examples of using the 
CLOSELIBRARY function can be found in Listing 11-2. 

Listing 11-2. Using the Exec CLOSELIBRARY Function 

CLOSING THE DOS LIBRARY 
(COMPANION TO EXAMPLE IN 
LISTING 11-1) 
PLACE BASE ADDRESS OF EXEC 
LIBRARY INTO A6 
MOVE STORED ADDRESS OF DOS 
JUMP TABLE TO Al 
NOW USE EXEC'S CLOSELIBRARY 
FUNCTION 



MOVE.L 4,A6 
MOVE.L _D0SBASE,A1 



JSR 



LV0.CL0SELIBRARY(A6) 



_DOSBASE DC.L 



MOVE.L 4,A6 

MOVE.L _INTBASE,A1 

JSR LVO.CLOSELIBRARY(A6) 



_INTBASE DC.L 



DATA DECLARATION 

HERE'S WHERE TO PUT THE 

DOS BASE ADDRESS 

WHEN 
THE LIBRARY WAS OPENED 

THIS EXAMPLE ALSO SHOWS WHY 
ITS A GOOD IDEA TO S/S/E THE 
BASE ADDRESS OF A 
LIBRARY YOU OPEN - BECAUSE 
LATER IT IS NEEDED TO CLOSE 
THAT LIBRARY 

CLOSING THE INTUITION LI- 
BRARY (COMPANION TO EX- 
AMPLE IN LISTING 1) 

PLACE BASE ADDRESS OF EXEC 
LIBRARY INTO A6 
MOVE STORED ADDRESS OF IN- 
TUITION LIBRARY INTO Al 
NOW USE EXEC'S CLOSELIBRARY 
FUNCTION 

DATA DECLARATION 

; WHERE THE BASE ADDRESS OF 
; LIBRARY WAS PLACED 



Because the Exec library (called the Sys library by 
ASM68010) is always open, it has to have a stable base jump 
table address. As mentioned above, this base address is mem- 
ory location 4. This location is called ABSEXECBASE or 
SYSBASE (by ASM68010). It's the only fixed memory location 
used by the Amiga operating system. Adventurous program- 
mers can access the entire system using the functions in the 
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Exec library to access other libraries and their functions. 

Libraries as families of functions. You must understand 
that libraries represent families of functions. All the functions 
in a given library perform either similar functions or related 
functions. To draw a line or a circle, you would call the 
Graphics library. To perform floating-point multiplication or 
division, you would have to call a function in the MathFFP 
(fast floating-point math) library. 

This is a crucial concept in Amiga machine language pro- 
gramming. Libraries provide your program with access to 
built-in software functions for graphics, Intuition, AmigaDOS, 
floating-point math, and more. Both the OPENLIBRARY and 
CLOSELIBRARY functions are in the Exec library (which is al- 
ways open). 

OPENLIBRARY requires one parameter: a pointer to the 
name of the library declared as null-terminated text. As the 
name implies, null-terminated text is a string of characters that 
ends with a byte containing the value 0. An example would 
appear in memory as LIBRA.RYNAME0, where the byte in- 
dicates the end of the string. The parameter passed when 
opening a library is the address of the first character in the 
string (in this case, the letter L ). 

CLOSELIBRARY requires one parameter: the base address 
of the library being closed. Both the OPENLIBRARY and 
CLOSELIBRARY functions expect their parameters to be 
placed in address register Al, prior to their use. 

Advanced programmers can build their own Amiga librar- 
ies by collecting the function addresses in a jump table. The 
techniques for this are described in the Amiga ROM Kernel 
Manual: Exec. They are beyond the scope of this book. The 
programs in this book will use the Amiga libraries for j j 

AmigaDOS, Intuition, graphics, fast floating-point math, and L — ' 

transcendental floating-point math. 

An example of a non- Amiga library is the LIVE. LIB li- j I 

brary of functions used by the A-Squared LIVE high-speed ' — ' 

video digitizer. It contains functions just for use with that 
hardware accessory. The LIVE digitizer has such special timing j I 
requirements that its own library must be used. There are «— ' 

times, when LIVE is operating, that the Intuition library can- 
not be used at all. The A-Squared programmers had to supply j j 
an alternative to the Intuition library just for use with their - 
hardware. 
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While none of the programs in this book require special 
libraries, advanced programmers may find it useful to learn 
how to make their own libraries for custom applications. Once 
you learn how to program with the Amiga's libraries, you'll 
easily adapt to using other specialized libraries. 

The code for opening and closing libraries is similar 
among libraries. The main difference is the pointer to the 
name of the library used during the opening phase. 

Library macros. Since opening libraries is a fairly stan- 
dardized procedure, it's a perfect candidate for a macro. List- 
ing 3 shows some relevant macros which are provided in the 
MACROS.ASM file. Library functions are called by placing the 
base address of the opened library into A6 and making a JSR 
relative to A6. Examples in this book almost always use the 
SYSLIB, INTLIB, MATHLIB, GFXLIB, or DOSLIB macros to 
simplify calling a library function. These macros assure that a 
library base address is placed into A6. They also code the JSR 
instruction and insert the LVO. prefix to all function names. 
These niceties reduce repetitive typing involved in calling li- 
brary functions. 

Listing 11-3. Macros Useful for Accessing Libraries (See 
MACROS.ASM) 

A MACRO TO SET UP A CALL TO ANY LI- 
; BRARY FUNCTION (LIKE OPENLIBRARY) 



LIBCALL 


MACRO 








MOVE.L 


\1,A6 


; PLACE LIBRARY'S BASE ADDRESS INTO A6 




JSR 


LVO.\2(A6) 


; JUMP TO NAMED SUBROUTINE IN THE 
; LIBRARY 


I 


ENDM 




A MACRO TO SET UP A CALL TO AN EXEC LI- 
BRARY FUNCTION 


SYSLIB 


MACRO 








LIBCALL 


SYSBASE, \ 1 


; USE LIBCALL MACRO, WITH SYSBASE (4) AS 
; PARAMETER 




ENDM 




A MACRO TO SET UP A CALL TO A DOS LI- 
BRARY FUNCTION (ASSUMING LIBRARY 
OPEN) 


DOSLIB 


MACRO 








LIBCALL 


-DOSBASE, \ 1 


; USE LIBCALL MACRO, WITH DOSBASE AS 



PARAMETER 
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ENDM 
; A MACRO TO SET UP A CALL TO A MATH LI- 

; BRARY FUNCTION 

MATHLIB MACRO - 

LIBCALL _MATHBASE,\1 

ENDM U ~ ' 



u 



Calling a Library Function 

Table 11-2 provides a list of the Exec functions (functions 
found in the Exec Library) used in programs in this book, as 
well as the registers used to pass parameters 

Most library functions require that you place pointers or 
data in registers before calling them. This is called set-up. Ta- 
ble 11-2 shows the set-up required by some of the Exec 
functions. 

Results. All library function calls return a result. This re- 
sult can usually be found in data register DO. Many functions 
simply place a in data register DO if the function failed, and 
a 1 if the function succeeded. 

Later on, you'll encounter library functions that return a 
pointer to a structure created by the function. Floating-point 
math library functions leave the result of their operation in 
DO. Functions from different libraries pass parameters to regis- 
ters in different ways. Exec functions usually use address regis- 
ter Al. DOS functions pass parameters in data registers Dl, 
D2, and D3. INTUITION may use A0-A2, and D0-D3 for 
passing parameters to a function. 

It should be noted that although all functions pass results, 
sometimes these results are irrelevant. Under some circum- 
stances, you won't care what the result is, or you'll be able to 
tell without checking the result. For instance, when some j 

functions fail, the computer will crash (cease operating), which l —~ J 
would make it both impossible and redundant to check for a 
result. 

Four-step library-calling process. When you read 
through Listing 11-5, try to see the four-step process used in 
calling a library function: j j 

• Open the library. 

• Place parameters for desired function in appropriate registers. .- — 

• Call the function. 1 | 

• Test the number returned in DO for errors or desired results. 
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Now that you've seen how to open and close libraries, 
and you've reviewed some macros that make programming 
with library functions easier, take a moment to reexamine 
some examples shown in Listing 11-1. Listing 11-4 shows two 
of the examples from Listing 11-1. The major difference be- 
tween the examples in the two listings is the use of macros in 
place of long-hand source code. 

Listing 11-4. Opening Libraries Using Macros 

; DATA DECLARATIONS NOT SHOWN 

OPENING THE DOS LIBRARY 



LEA 


D0SNAME.A1 


SYSLIB 


OPENLIBRARY 


TST.L 


DO 


BEQ 


ERROR_DOSLIB 


MOVE.L 


D0,_DOSBASE 


LEA 


INTNAME.A1 


SYSLIB 


OPENLIBRARY 


TST.L 


DO 


BEQ 


ERROR_INTLIB 


MOVE.L 


DO,_INTBASE 



OPENING THE INTUITION LIBRARY 



Listing 11-5 illustrates the process of opening a library, 
placing the parameters in appropriate registers, and using 
macros to call library functions. 

Listing 11-5. Library Function Calls with Parameter Passing in 
Registers 









OPENING AND USING A MATH LI- 


n < 






BRARY FUNCTION 






PARAMETERS IN D0,D1 




LEA 


MATHNAME.A1 


PTR TO TEXT NAME OF LIBRARY 


n 


SYSLIB 


OPENLIBRARY 


INT0A1 

EXEC LIBRARY 'OPEN OTHER 

LIBRARY' 




TST.L 


DO 




n 


BEQ 


ERROR-MATHLIB 




MOVE.L 


DO,_MATHBASE 


SAVE POINTER TO MATH LIBRARY 








BASE 


n 


MOVE.L 


VARIABLEl.Dl 


PUT FLOATING POINT NUMBER 1 






INTOD1 


MOVE.L 


VARIABLE2,D0 


PUT FLOATING POINT NUMBER 2 








INTO DO 



125 



Chapter 11 



MATHLIB SPADD 




MOVE.L 


DO.SUMOF 


LEA 


INTNAME.A1 


SYSLIB 
TST.L 
BEQ 
MOVE.L 


OPENLIBRARY 

DO 

ERROR 

DO_INTBASE 


MOVE.L 


NEWWINDOW.A0 


INTLIB OPENWINDOW 




TST.L 
BEQ 


DO 
ERROR 


MOVE.L 


DO.THISWINDOW 



; ADD TWO NUMBERS WHICH 

; WERE IN D0.D1 

; RESULT OF ADDITION IS IN DO 

OPENING AND USING AN INTU- 
ITION LIBRARY FUNCTION 

; PARAMETER FOR OPENLIBRARY 

; FUNCTION INTO Al 



; SA/E POINTER TO INTUITION 

; LIBRARY BASE 

; RVRAMETER FOR OPENWINDOW 

; FUNCTION INTO AO 

NEWWINDOW IS ADDRESS OF A 

NEWWINDOW STRUCTURE 

; NOW CALL THE INTUITION 

; LIBRARY FUNCTION 

; SEE IF RESULT IN DO IS 

; IF IT WAS, THAT'S AN ERROR OF 

; OPENWINDOW 

; IF IT WASN'T, SET PTR TO 

; WINDOW STRUCTURE 

CAME BACK IN DO. LETS SAVE IT. 



In closing this introduction to the concept of libraries, 
here's an example of using the SYSLIB macro to close a library 
in Listing 11-6. 

Listing 11-6. Closing Libraries Using the SYSLIB Macro (See 
MACROS.ASM) 



MOVE.L 
SYSLIB 



MOVE.L 
SYSLIB 



_INTBASE,A1 
CLOSELIBRARY 



_DOSBASE,Al 
CLOSELIBRARY 



CLOSING THE INTUITION LIBRARY 
DATA DECLARATIONS NOT SHOWN 

;PLACE LIBRARY BASE ADDRESS INTO Al 
;CLOSE THE LIBRARY 

CLOSING THE DOS LIBRARY 



Be sure you understand the fact that libraries are orga- 
nized into families of software functions. For instance, all 
graphics functions may be found in the Graphics library; 
floating-point math functions are in the MathFFP library; 
functions relating to mouse input and windows are in the In- 
tuition library; and so on. 
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This concept is central to the entire process of Amiga ma- 
chine language programming. 

Beginners' Note 

You will notice that whenever libraries are discussed, they are 
referred to by name. The functions within these libraries are 
also called by name. For instance, LVO.OPENLIBRARY is a 
function in the Exec library. 

The MC68000 microprocessor has no idea what 
LVO.OPENLIBRARY is. The name must be defined as a num- 
ber somewhere, because numbers are the only thing a micro- 
processor understands. 

To see the numerical definitions of the Exec functions used 
by programs in this book, read the SYSEQUATES.ASM file in 
the previous chapter. There, you will find LVO.OPENLIBRARY has 
a numerical equivalent of $FFFFFDD8. The SYSEQUATES.ASM file 
must be included by the program's source code in order to allow 
the computer to understand what is meant by the text string 
LVO.OPENLIBRARY. If you read through the HEADER file in 
the previous chapter, you'll see that SYSEQUATES.ASM is al- 
ways included. 

The SYSEQUATES.ASM file provided in this book is very 
short. For the sake of space and typing time, it was limited to 
those numerical definitions required by the programs in this 
book. Exec contains many more UIO.xxxxxx functions. If you 
wish to see them all, open the Amiga ROM Kernel Intuition 
Manual to Appendix D for a brief discussion of Amiga library 
offsets, and then review the tables of numbers that follow. 

Table 11-2. Exec (SYS) Library Functions and Parameter 
Registers 

Name Description Parameters 

ALLOCMEM Allocate memory Size,Type 

FREEMEM Deallocate memory Ptr,Size,Type 

OPENLIBRARY Open a library Name, Version 

CLOSELIBRARY Close a library Ptr to library 

FINDTASK Get task structure Al = 

FORBID Stop task switching 

PERMIT Allow task switching 



Registers Result 

D0,D1 Ptr/0* 

A1,D0,D1 /crash 

A1,D0 Ptr/0 

Al /crash 

Ptr/0 



WAITPORT Wait on port message Ptr to port AO 

GETMSG Get arrived message Ptr to port AO Ptr 

REPDCMSG Reply to message Ptr to message Al 

* The abbreviation Ptr indicates that the result returned by the function is a pointer. If appears 
under the heading Results, a 1 indicates a success and a indicates a failure. Crash indicates that 
the program will crash the computer if the function call fails. If no result is listed, the result is 
irrelevant. 107 
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Because the Amiga is multitasking and loads programs and j ] 

data into memory in different locations as needed, it must 1 J 

contain some internal functions to keep track of which parts of 
memory are filled and which are available for loading new 
data or programs. 

Allocating and Deallocating Memory 

The Amiga operating system maintains a heap of memory and 
a freelist of addresses and amounts of memory not in use. Pro- 
grams don't usually manipulate these lists because the operat- 
ing system takes care of them automatically (although 
advanced programming techniques on the Amiga sometimes 
involve creation of subtasks, which manage their own memory 
heaps). 

Allocating memory for use by a program (arrays and 
other data structures) is simple and straightforward. There are 
several methods for claiming memory when your program 
needs it. 

Using ALLOCREMEMBER and FREEREMEMBER. The 
simplest method for claiming some free memory for your pro- 
gram's use involves two Intuition library functions called 
ALLOCREMEMBER and FREEREMEMBER. 

When your program calls ALLOCREMEMBER, it must tell 
the operating system how much and which type of memory to 
allocate. (The types of memory will be explained in the next 
section.) When ALLOCREMEMBER returns, it provides the ad- 
dress of a free region of memory that has been allocated. The 
address is returned in DO. If the function fails, then DO will 
contain a 0, instead. At the same time, ALLOCREMEMBER 
automatically adds the information about the allocated mem- 
ory to a special REMEMBER list. That means a program may 
call ALLOCREMEMBER several times to secure several chunks 
of memory, which are automatically remembered without any 
further action on your part. 

When your program is finished with the memory it has 
allocated, it must return it to the heap. This is accomplished 
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with a single call to FREEREMEMBER. The only drawback to 
this procedure is that the separate chunks of memory obtained 
on a "chunk-by-chunk" basis must then be deallocated the 

P - "] same way, which is difficult to do. You should allocate mem- 
1 ory using ALLOCREMEMBER when the memory is needed 
throughout the program. Then, at the end of the program, a 

r*1 call to FREEREMEMBER deallocates all of this memory at 

■ ' once. 

The STARTUP. ASM program in Chapter 14 has a built-in 
call to FREEREMEMBER in its final section, so you won't have 
to be concerned with this function as long as you're using the 
conventions of this book. If you use STARTUP.ASM, all the 
memory allocated by ALLOCREMEMBER calls is automati- 
cally returned when your program shuts down. Remember 
that ALLOCREMEMBER and FREEREMEMBER are functions 
in the Intuition library. You must open that library before you 
call these functions. 

ALLOCREMEMBER and FREEREMEMBER are very 
convenient functions to use because all the addresses of allo- 
cated memory chunks are remembered by the Amiga, enabling 
their simultaneous deallocation with FREEREMEMBER. In or- 
der for the Amiga to keep track of this list, both ALLOCRE- 
MEMBER and FREEREMEMBER use a long word declared in 
the program. Usually this long word is named REMEMBER- 
KEY to indicate that it is the KEY to the REMEMBER list. The 
data declaration in a program is simply: 

REMEMBERKEY DC.L ;PROVIDE A LONG WORD FOR AMIGA 

TO REMEMBER ALL THE ALLOCREMEMBER 
; ALLOCATIONS 

i — ( The STARTUP.ASM program has this data declaration 

i | built in. STARTUP.ASM, thus, assumes that you will use 

ALLOCREMEMBER in your programs. If you don't, the data 
P— I declaration will keep its value and STARTUP.ASM will skip 
j I over its FREEREMEMBER call. If you've used ALLOCRE- 
MEMBER somewhere in the program, the REMEMBERKEY 
— value will change. STARTUP.ASM detects it and calls 
! | FREEREMEMBER when your program ends. If you use 

STARTUP.ASM as part of your program, you do not need to 
r— . declare your own REMEMBERKEY. It's possible to declare sev- 
1 I eral REMEMBERKEYs and handle more than one list of allo- 
cated chunks. Each list is associated with a different 
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REMEMBERKEY and can be deallocated by a separate call to 
FREEREMEMBER. If you wish to have multiple lists of allo- 
cated memory, consider using the following method instead. 

Using ALLOCMEM and FREEMEM. Sometimes it's nec- 
essary to keep track of some memory allocations separately 
and directly through your program. In these cases, we may 
use two of the functions in the Exec library — ALLOCMEM 
and FREEMEM. 

You don't have to open any libraries to use these, because 
Exec is always open. These are used when some memory will 
be returned to the heap, separately from a large list being 
managed by ALLOCREMEMBER. Use ALLOCMEM and 
FREEMEM (the address of the allocated memory comes back 
in DO when you call ALLOCMEM) to get memory that is to be 
handled separately. These functions don't create a REMEM- 
BER list, so they're more efficient than ALLOCREMEMBER 
and FREEREMEMBER. 

Call ALLOCMEM with parameters designating the quan- 
tity and type of memory desired. (An explanation of the types 
of memory available can be found in the following section.) 
The address (or a value, in the event of a failure) of the allo- 
cated chunk is returned in DO. Programs should store the ad- 
dresses of memory chunks obtained in order to return them to 
the heap when the operation requiring extra memory is com- 
plete. You deallocate memory obtained using ALLOCMEM, by 
using the function FREEMEM. 

You may recognize some similarity between this process 
and the opening/closing of libraries. Memory is another sys- 
tem resource that must be returned after use. The taking and 
returning of these resources is usually managed by pairs of 
functions like OPEN/CLOSE or ALLOCATE/FREE, or , - 1 

ALLOCREMEMBER/FREEREMEMBER. 1_J 

It's possible to allocate one large memory chunk at the 
start of a program and subdivide it for use, but it's more 
convenient to call ALLOCREMEMBER whenever more mem- 
ory is needed. This way, more memory remains on the heap, 
providing for smoother operation and more resources for other ; ~, 

applications that may be running. The Amiga usually has a lot ] I 

of small chunks of memory available for use, and only a few 

large ones. Be wise in your use of memory. , - , 

Size of memory allocated. The Amiga always allocates | | 

memory in multiples of 8 bytes. You may request a memory 
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!""""] allocation of 3 bytes, but the Amiga will allocate 8. If you re- 
' quest 31 bytes, the Amiga will allocate 32 bytes. 

Memory allocation has another important feature: All ad- 
r"*1 dresses of allocated chunks of memory start on long-word 
' boundaries. That is, these addresses can be evenly divided by 
four. Because the MC68000 expects instructions and most data 
["""] to be aligned on even addresses in memory, the allocation 

functions relieve you of the responsibility for aligning your ar- 
rays and other data. 

Specific methods for using ALLOCREMEMBER/ 
FREEREMEMBER and ALLOCMEM/FREEMEM are shown in 
Listing 12-1. You may also study the Amiga ROM Kernel Refer- 
ence Manual: Exec and the Amiga Intuition Reference Manual for 
more information on memory allocation. Before showing the 
programming examples and macros for memory allocation, we 
need to learn about the different types of memory in an 
Amiga system. 

Types of Memory 

The Amiga operating system uses three types of memory: 
chip, fast, and public memory. 

Chip memory. The special graphics, sound, and I/O 
chips in an Amiga give it much of its power, but they also im- 
pose a limitation on programs. The special chips can only see 
part of the Amiga's potential memory range. In an Amiga with 
512K or less memory, the special chips can see all of the 
memory. This lower 512K of the Amiga's total memory space 
is called chip memory (MEMF—CHIP is its symbolic name). 
Fast memory. Any expansion memory beyond the first 
-— ( 512K is called fast memory. It's called fast because the special 
( j chips usually can't see it and, therefore, processing this mem- 
ory is not momentarily blocked through bus contention. Bus 
,__ - contention is the result of several processors trying to use the 
| same bus. It's analogous to two people trying to make tele- 
phone calls on a party line. Courtesy will result in one of the 
__* calls being made now and the other later, but for a few sec- 
! J onds, both people are trying to dial, to talk, and to figure out 
the problem at the same time. The Amiga has a party line to 
_— memory within the first 512K and a private line to fast (or ex- 
j j pansion) memory. (The Amiga 500 may experience some bus 
contention even on expansion memory.) 
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The symbolic name for fast memory is MEMF_FAST. j I 

Public memory. There is one other type of memory — ' 

called public memory. Public memory may be fast memory (if 
it's available) as a first choice, and chip memory as a second j 

choice. Its special symbol is MEMF_PUBLIC. ' — ' 

Public memory may have another meaning in the future if 
Commodore enhances the operating system to include memory I j 
protection, a feature of larger computers. Public memory is ^ — 

memory accessible to all active tasks. Other memory desig- 
nated for use by a single task might be called private memory, 
and could be protected from interference by other tasks. 

The current Amiga operating system doesn't provide pro- 
tection, so it's easy for one task to interfere with another. 
That's one reason it's so important to allocate memory and re- 
sources for a task carefully, and to assure that they are care- 
fully deallocated when the task is done. 

When you ask for public memory, the operating system 
will decide which type you are given. Be sure to allocate chip 
memory to create a graphic image, or screen display, or sound. 
Fast memory is usually used for program code, data arrays, 
and variables. When you request public memory for data ar- 
rays, you'll be given fast memory if it's available. Since some 
users of your program may have expansion memory and some 
may not, asking for public memory allows for the greatest 
compatibility. The operating system's convention of using fast 
memory first allows you to keep chip memory clear for sound 
and graphics uses. 

The symbols used to request memory are MEMF_FAST, 
MEMF_PUBLIC, and MEMF_CHIP. A fourth symbol you'll 
need to know is MEMF_CLEAR. When this symbol is used 
with the call for memory, the allocated memory will be 
cleared. Each bit within the allocated memory will be set to 0. 

These symbols are defined in the SYSEQUATES.ASM file. 
Example program fragments that allocate, and free memory, 
are shown in Listings 12-1 and 12-2. ' — ' 



Listing 12-1. Using the Intuition and Exec Library Memory Allo- 
cation Functions 

USING ALLOCREMEMBER TO OBTAIN A 
CHUNK OF 40 BYTES FOR AN ARRW 

THIS EXAMPLE ASSUMES THE INTUITION 
LIBRARY IS OPENED ELSEWHERE IN THE 
PROGRAM 
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MOVE.L 


_INTBASE,A6 


MOVE.L 


#40,D0 


MOVE.L 


#MEMF_CHIP,D1 


MOVE.L 


REMEMBERKEY,AO 



JSR LVO.ALLOCREMEMBER(A6) 

TST.L DO 

BEQ ERROR-ALLOCREMEM 

MOVE.L DO.ARRWBASE 



MOVE.L 


#40,D0 


MOVE.L 


#MEMF_FAST,D1 


MOVE.L 


4,A6 


JSR 


LVO.ALLOCMEM 


TST.L 


DO 


BEQ 


ERR-ALLOCMEM 


MOVE.L 


DO.ARRATBASE 



AND ITS BASE ADDRESS HAS BEEN 
STORED IN A LABELED LOCATION, 
-INTBASE 

USING THE INTUITION LIBRARY 
YOU NEED 40 BYTES OF MEMORY IN 
ONE CHUNK 

YOU WANT CHIP MEMORY THIS TIME 
A LABELED LOCATION USED AS REFER- 
ENCE TO THE 

REMEMBER LIST BY THE OPERATING 

SYSTEM 

REMEMBERKEY IS FOUND IN THE 

STARTUP.ASM 

GET SOME MEMORY 
WAS AN ERROR MADE? 
IF YES, BRANCH TO AN ERROR 
SUBROUTINE 

If NO, S/B/E THE ADDRESS OF THE 40- 
BYTE CHUNK AT 
A LABELED LOCATION IN MEMORY 

USING THE EXEC LIBRARY ALLOCMEM 
FUNCTION TO GET SOME MEMORY 

AMOUNT IN DO 

TYPE OF MEMORY IN Dl 

EXEC LIBRARY BASE ADDRESS INTO A6 

GET SOME MEMORY 

ERROR? 

IF YES, BRANCH TO ERROR HANDLER 

IF NO, SWE THE ADDRESS OF THE 40- 

BYTE CHUNK 



Listing 12-2. Returning Allocated Memory with FREEREMEMBER 
or FREEMEM 



n = 






miS CODE FREES MEMORY ALLOCATED 






BY FIRST EXAMPLE IN LISTING 12-1. 




MOVE.L 


ARRA'BASE.Al 


ADDRESS OF MEMORY TO BE 


n 






DEALLOCATED 


MOVE.L 


#40,D0 


HOW MUCH MEMORY TO GIVE BACK 




MOVE.L 


_INTBASE,A6 


USING THE INTUITION LIBRARY 


n 


MOVE.L 


REMEMBERKEY.A0 


TELL SYSTEM WHERE THE LIST OF 






REMEMBERED 






MEMORY ALLOCATIONS STARTS. THIS 








REMEMBERKEY 


n 






IS IN YOUR DATA DECLARATIONS IF YOU 






WANT TO 








USE YOUR OWN NAME FOR IT 








STARTUP.ASM HAS A REMEMBERKEY WITH 
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THAT 
NAME 
JSR LV0.FREEREMEMBER(A6) ; GIVE THE MEMORY BACK 

DEALLOCATING MEMORY USING THE EXEC 
LIBRARY FREEMEM FUNCTION 

MOVE.L 4,A6 ; USE THE EXEC LIBRARY BASE ADDRESS 

INA6 

TELL SYSTEM WHERE THE CHUNK IS 
TELL SYSTEM HOW BIG CHUNK IS 
FREE THE MEMORY 



MOVE.L 
MOVE.L 
JSR 



ARRWBASE.Al 

#40,D0 

LVO.FREEMEM(A6) 



This is another situation in which macros are called for. 
The MACROS.ASM file has two macros that simplify the use 
of the ALLOCREMEMBER function. They're shown here, for 
reference, in Listing 12-3. (See the MACROS.ASM file for ad- 
ditional macro listings.) Note that both macros make use of 
the same REMEMBERKEY. 

Listing 12-3. Macros for Using Intuition Library 
ALLOCREMEMBER 

MACRO FOR 

ALLOCREMEMBER WITH 
CHIP MEMORY 
ASSUMES INTUITION LI- 
BRARY IS OPEN 

POINTER TO 

REMEMBERKEY.AMOUNT, 
[ERRORBRANCH] 

\1,A0 ; ADDRESS OF 

REMEMBERKEY POINTER 

IN 

AO 

DO ; MACRO TO CLEAR DO, 

MAKE 
DO = 

MOVE AMOUNT INTO DO 
WE WANT CLEARED CHIP 
MEMORY 
MACRO TO CALL 
INTUITION 
ALLOCREMEMBER 

'\3V ; IF THERE IS AN 'ERROR' 

PARAMETER 

DO ; THEN USE IT, OTHERWISE 

ERROR CHECKING 
\3 ; MUST BE IN YOUR OWN 

CODE FOLLOWING THIS 
MACRO 



REMEMBERCHIPMEM MACRO 



LEA 



ZERO 



MOVE 
MOVE.L 



\2,D0 
#MEMF_CHIP!MEMF_CLEAR,D1 



INTLIB ALLOCREMEMBER 



IFNC 
TST.L 
BEQ 

ENDC 

ENDM 



u 
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REMEMBERPUBMEM MACRO 



LEA 

ZERO 

MOVE 

MOVE.L 

INTLIB 

IFNC 

TST.L 

BEQ 

ENDC 

ENDM 



MACRO FOR 

ALLOCREMEMBER WITH 
PUBLIC MEMORY 

POINTER TO 

REMEMBERKEY.AMOUNT, 

[ERRORBRANCH] 



\1,A0 
DO 

\2,D0 

#MEMF_PUBLIC!MEMF_CLEAR,D1 
ALLOCREMEMBER 
'\3'," 
DO 

\3 



Listing 12-4 shows the example from Listing 12-1, 
accessing the ALLOCREMEMBER function using macros in- 
stead of long-hand code. 

Listing 12-4. Macro Version of First Example in Listing 12-1. 



REMEMBERCHIPMEM 
MOVE.L 



REMEMBERKEY,#40,ERROR_ALLOCREMEM 
DO,ARRAYBASE 

NOTE THIS EXAMPLE ASSUMES INTUITION LIBRARY IS 

ALREADY OPEN AND THAT THE 

PROGRAM'S DATA DECLARATIONS INCLUDE A 

REMEMBERKEY AND AN ARRWBASE (BOTH 

SHOULD BE LONG WORDS BECAUSE THEY MUST EACH 

CONTAIN A MEMORY ADDRESS OF 32 

BITS.) 



This example shows how most of the memory allocations 
are handled in this book's programs. Macros are used when- 
ever possible to shorten and simplify the program source code. 
Proper memory allocation and deallocation are requirements 
common to most Amiga programs. Be sure this concept and 
the relevant library functions are familiar to you before trying 
to use these techniques. You'll find many additional examples 
in the program listings in subsequent chapters. 
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The term structure is from the C language. Structures provide 
storage space for variables and data used by the operating sys- 
tem and application programs. The concept of structures goes 
hand-in-hand with the Amiga library software organization. 
Structures are simply data tables. Dozens of structures 
were defined by the programmers of the Amiga, each with a 
name appropriate to its function. One of the essential docu- 
ments of the Amiga is a list of the structure names and 
contents. 

Amiga's Data Tables 

Much machine language work on the Amiga involves provid- 
ing memory space for structures, filling them with data, and 
reading data from them during the operation of the program. 

Before you can call most of the library functions, you 
must provide parameters or data. Some library functions re- 
quire that data be placed in data or address registers. How- 
ever, other library functions require far more data than you 
could fit into the 16 data and address registers. When that 
happens, you may be called upon to set up a structure and 
pass the address of the structure to a library function. A struc- 
ture can be as large as necessary to contain the information 
the library function needs. It may contain subsections of byte, 
word, and long-word data. 

An example is the OPENWINDOW function. Prior to call- 
ing it (it is in the Intuition library), a structure called 
NEWWINDOW must be created and filled with information 
about the window to be opened. Data about the size, title, 
gadgets, and other features you want the window to have, are 
placed into the NEWWINDOW structure. Then, when you call 
the OPENWINDOW function, the only data you put into the 
registers prior to the call is the address of the NEWWINDOW 
structure. 

Declaring structures in source code. The machine lan- 
guage programmer can build structures in several ways. Use 
the DC.x assembler directives (DC.B, DC.W, DC.L, and 
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DCB.B) to declare storage space for a structure such as 
NEWWINDOW, in the program source code. If you use this 
method to make a separate structure allocation in code for 
each one that's required, you'll soon find that you have a 
huge source file with a lot of repetitive structures needed by 
the program. 

Listing 13-1 is an example of using the DC* directive to 
fill a NEWWINDOW structure. The use of NEWWINDOW 
structures will be discussed further in the INTUITION WIN- 
DOWS chapter. The point here is simply to show one way 
structures can be placed into your program source code. 

Listing 13-1. Declaring and Filling a Structure (NEWWINDOW) 
in Source Code 







LABELED BEGINNING ADDRESS OF THIS 






STRUCTURE 


DC.W 


0,0 


TWO WORDS, LEFTEDGE AND TOPEDGE 
VARIABLES 


DC.W 


300,100 


WINDOW WIDTH AND HEIGHT 


DC.B 


0,1 


TWO BYTES, THE COLOR REGISTERS FOR 
DRAWING WJNDOW 


DC.L 


CLOSEWINDOW 


THIS IS AN'IDCMP FLAG 


DC.L 


WINDOWCLOSE!WINDOWDRAG!$INDOWSIZING!WINDOWDEPTH 



THESE FLAGS DICTATE THE APPEARANCE OF 

USUAL 

WINDOW GADGETS LIKE CLOSE, DRAG, SIZE, 

AND SO ON. 

THE T MEANS 'OR' TO THE ASSEMBLER 



DC.L 





NO GADGETS FOR THIS WINDOW 


DC.L 





NO POINTER IMAGE FOR THIS WINDOW 


DC.L 


TITLE 


POINTER TO NULL-TERMINATED TEXT 
WINDOW TITLE 


DC.L 





NO SPECIAL SCREEN FOR THIS WINDOW 


DC.L 





NO SPECIAL BITMAP FOR THIS WINDOW 


DC.W 


40,20 


TWO WORDS, MINIMUM WINDOW WIDTH AND 
HEIGHT 


DC.W 


630,200 


TWO WORDS, MAXIMUM WINDOW WIDTH 
AND HEIGHT 


DC.W 


WBENCHSCREEN 


TYPE OF SCREEN WINDOW WILL BE IN 



The program code to open the window specified by this 
structure is: 



LEA NEWWINDOW.A0 

INTLIB OPENWINDOW 



PUT ADDRESS OF THE NEWWINDOW STRUCTURE 

INA0 

USE INTLIB MACRO TO CALL OPENWINDOW 

LIBRARY FUNCTION 
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Using subroutines to allocate and fill structures. An- 
other method uses subroutines to allocate memory for each ^~^ 
structure and fill the data fields with standard values. The pro- 
grammer must then only make modifications to the standard j i 
values as needed. ^ — 

This book includes a family of subroutines that allocate 
memory and fill structures used for menus, windows, gadgets, j I 
and other elements of the Intuition system. The drawback to ^-"—' 

using the subroutines is that they enlarge the source and ob- 
ject code. If you only need a structure of a certain type once, 
you may want to declare it in your code and leave out the re- 
lated subroutine. For menus and other Intuition tools, it's eas- 
ier to use the subroutines provided here (or your own) 
because many structures are created for most Intuition tools. 
The family of subroutines for handling structures, in this 
book, are in the support code files that are part of the type-in 
include files. The include files are named WINDOWS. ASM, 
GADGETS.ASM, and so on, and will appear in upcoming 
chapters. 

The subroutines use standard sets of values for certain In- 
tuition structures. These may not always be the ones you want 
in your own programs. Modify the subroutines any way you 
need, or write code that does the modifications your programs 
require. The latter method works well when only a slight 
modification on a structure is needed. Listing 13-2 is an ex- 
ample of the MAKEAWINDOW subroutine allocating mem- 
ory, filling a NEWWINDOW structure, and then opening the 
window. 

Listing 13-2. Using a Subroutine (MAKEAWINDOW) to Allocate 
and Fill a NEWWINDOW Structure and Open a Window 

USE CODE ONLY TO DICTATE THOSE field VALUES 
; THAT ARE UNIQUE 

PLACE LEFTEDGE VALUE OF 10 IN DO 

PLACE TOPEDGE VALUE OF 10 IN Dl 

PLACE WIDTH VALUE OF 300 IN D2 

PLACE HEIGHT VALUE OF 100 IN D3 

LET THE SUBROUTINE DO THE WORK OF 

ALLOCATING 
AND FILLING THE NEWWINDOW 'STANDARD' SLOT 
VALUES 
AND OPENING THE WINDOW 
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MOVE.W 


#10,D0 


MOVE.W 


#10,D1 


MOVE.W 


#300,D2 


MOVE.W 


#100,D3 


BSR 


MAKEAWINDOW 



n 
n 
n 
n 
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This example refers to the MAKEAWINDOW subroutine 
presented in a later chapter. It's used here to make the point 
that you're free to write your own subroutines for doing much 
of the drudgery of allocating and filling structures. The only 
alternative is to declare them within your program source 
code, as shown above. A program with more than a few sim- 
ple structures can become very long. The subroutine method 
saves a lot of code and typing. 

One more aspect of structures is important to program de- 
sign: Each of the fields in a structure has a name defined in 
the include files. If you will think of databases for a moment, 
this may become clear. A database has records, which are sim- 
ilar to structures. Within each record are fields. Similarly, 
structures have fields. Generally, for the sake of order, data- 
base fields are named. They might bear names like Address or 
City. The first field of a NEWWINDOW structure is named 
NW.LEFTEDGE. 

NW.LEFTEDGE is a word of data indicating how far the 
window should be from the left edge of the screen. When you 
wish to assign a value to it, use the name NW.LEFTEDGE as 
an offset to an address register, to fill that field with a value. 
The assembler finds the correct value and substitutes it at the 
time of assembly. Therefore, it isn't necessary to memorize all 
the numeric offset values of fields within a structure. Simply 
remember the field names. Like NW.LEFTEDGE, most field 
names are logical and easily understood. 

The examples that fill structures with data values always 
use the field-naming scheme in the equate files. Since each 
data element of a structure is located at some fixed number of 
bytes (called an offset) from the beginning of the structure, the 
structure can be filled by using the base address and the off- 
sets. Listing 13-3 is an example using address register indirect 
with displacement addressing to fill in part of a NEWWINDOW 
structure. 
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Listing 13-3. Filling a NEWWINDOW Structure Using Indirect 
with Displacement Addressing 



LEA NEWWINDOW.A0 

MOVE.W #10,NW.LEFTEDGE(A0) 

MOVE.W #10,NW.TOPEDGE(A0) 

MOVE.W #300,NW.WIDTH(A0) 

MOVE.W #100,NW.HEIGHT(A0) 

MOVE.B #2,NW.DETAILPEN(A0) 

MOVE.B #3,NW.BLOCKPEN(A0) 



PLACE ADDRESS OF STRUCTURE IN AO 
MOVE 10 TO LEFTEDGE SLOT IN 
STRUCTURE 

MOVE 10 TO TOPEDGE SLOT IN STRUCTURE 
MOVE 300 TO WIDTH SLOT IN STRUCTURE 
MOVE 100 TO HEIGHT SLOT IN STRUCTURE 
MOVE 2 TO DETAILPEN SLOT 
MOVE 3 TO BLOCKPEN SLOT 



u 
u 



In Listing 13-3., the offsets NW.LEFTEDGE, NW.TOP- 
EDGE, and so on, are given numerical values by the assembler 
from the equate files. The four equate files GFXEQUATES.ASM, 
INTEQUATES.ASM, DOSEQUATES.ASM, and SYSEQUATES 
.ASM contain the definitions and offset field names of all the 
structures used in this book. 

Figure 13-1 may help you develop a mental picture of a 
structure. 



Figure 13-1. A Structure's Image in Memory 
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As a final note on offsets, you may be interested to know 
that neither the Amiga ROM kernel reference manuals nor the 
include files on the Metacomco assembler disk give individual 
numeric values for the named structure offsets. 

The official method of defining offset values is much 
more complicated than using an equate file. The Metacomco 
assembler creates these numerical values as a program is as- 
sembled. Equate files were used in producing the programs for 
this book on the grounds that they are simpler, and they make 
machine language programming on the Amiga more familiar 
to those used to machine language on other personal computers. 
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Amiga Program Startup 
Code 



Now that you've been prepared with the necessary infor- 
mation about Amiga programming techniques, memory alloca- 
tion, structures, and library usage, it's time to take a look at 
STARTUP.ASM. This program is intended to be used with 
most of the programs in this book. You already read a few ref- 
erences to it earlier in the text. 

Figure 14-1. Flow Chart of STARTUP.ASM Program Fragment 



-START 



SAUE STACKPOINTER 

COMMAND ADDRESS 
COMMAND LENGTH 
TASK ADDRESS 



-FIRST LINE 
LABELED: 
"_START" 




N-HORKBENCH 



CALL INPUT 



]\ 



CALL OUTPUT 
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CLI AS 
DEFAULT 
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OPEN DOS 
LIBRARV 
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MESSAGE 



USER'S 
CODE — » 



OPEN OTHER 

DESIRED 

LIBRARIES 



MAIN 
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CLOSE 
CONSOLE 
IF OPEN 



REPLV TO 

WORKBENCH 

MESSAGE 




OPEN A 

DOS CONSOLE 

FILE 



=n 



ATTACH CONSOLE 
TO TASK AS ITS 
DEFAULT I/O 
CHANNEL 



RETURN 
■ REMEMBER 
MEMORV 



CLOSE 

OPEN 

LIBRARIES 



RETURN 

FROM 

SUBROUTINE 
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Why is STARTUP.ASM needed? 

Amiga machine language programs usually have startup and 
ending sections. The startup section opens system resources 
(like libraries) and the ending section returns the resources to 
the system. All of the programs in this book, except HIWORLD, 
use a universal STARTUP.ASM program to accomplish this. 

At the end of the HEADER file is an INCLUDE direc- 
tive for the STARTUP.ASM file. The middle of the 
STARTUP.ASM program has a BSR (Branch SubRoutine) in- 
struction that directs the program flow to the entry point of 
your program file. Thus, the entry point of your SOURCE file 
should be labeled MAIN. 

Once you understand the operation of STARTUP.ASM, 
you're free to add to it or modify it to conform to your own 
applications. The first few lines of STARTUP.ASM deal with 
multitasking. There are a few lines of code which determine if 
the program was started up from the Workbench or a CLI. 
Then, it opens appropriate libraries according to its needs. 
Programs may use DOS, Intuition, Graphics, MathFFP, and 
MathTrans libraries. STARTUP.ASM may open them all. Once 
STARTUP.ASM has determined the program's parent task 
(either Workbench or CLI) and opened the libraries, it 
branches with the instruction BSR MAIN to the start of your 
program. 

Your program should end with an RTS instruction (Re- 
Turn from Subroutine). This will return the program flow to 
the ending portion of STARTUP.ASM. The ending portion 
closes all the libraries opened earlier and exits to the operating 
system. 

If you use the STARTUP.ASM file provided in this book, 
you'll only have to worry about programming. You won't 
have to open or close libraries; this will be done for you. 

The STARTUP.ASM file also declares a few bytes of data 
for all programs, and checks for errors while opening libraries. 
If STARTUP.ASM detects an error at this early stage, it has an 
exit routine that closes things down quickly. Your program 
won't even begin unless the STARTUP.ASM program has suc- 
cessfully completed its job. 

For more information about writing startup programs, see 
the Amiga ROM Kernel Reference Manual: Libraries and Devices. 
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The STARTUP.ASM Program |_J 

Listing 14-1 contains the program code for the STARTUP. ASM 
program. Using EMACS or your favorite text editor, type in 
and save this file, since it will be required for all the other ] ! 

programs in this book. Save this file with the name: 

DEV:RAMIT/INCLUDES/STARTUP.ASM 

This will place the STARTUP.ASM include file in its 
proper place on the DEV disk you began building in Chapter 10. 

STARTUP.ASM is the framework for a general-purpose 
Amiga machine language program. It plays the part of a tem- 
plate into which you can insert your own code, and which can 
be modified for your particular needs. Programs in this book 
are created by writing a source file and including STARTUP.ASM. 
The STARTUP.ASM file remains constant, entering and exiting 
from the multitasking operating system for all other programs. 

Since STARTUP.ASM will play such an important role in 
all subsequent programming, it would be worthwhile to exam- 
ine it to see how it works with your code. 

The STARTUP.ASM performs several functions in a well- 
managed sequence: 

• Saves critical registers 

• Determines whether this code was started from the CLI or 
the Workbench 

• Opens the DOS library 

• Sets up I/O pointers using DOS functions (if it entered from 
the CLI) 

• Opens default console I/O if entry was from the Workbench, 
and the Workbench console symbol is defined 

• Opens libraries conditionally if there are GFX, INT, and MAT 
definitions, and so on 

• Branches to user source code as a subroutine 

• After returning from user program code, it replies to the 
Workbench message and closes the default console, if 
necessary 

• Closes any open libraries I . 

• Restores critical registers and returns from subroutine | | 



U 
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The first line of STARTUP.ASM is labeled -START. 
All programs that appear later in this book begin with a 
BRA —START instruction. That forces them directly to the 
beginning of this code. 



Remember, the -START label is part of the STARTUP.ASM 
program. It marks the first instruction your programs should 
actually execute. It's the starting point for all programs except 
HIWORLD.ASM. Application program source code should 
start like this: 



BRA 



WBC EQU 
GFX EQU 

INCLUDE 



MAIN 



RTS 



-START ; BRANCH AROUND THE EQU AND 
; INCLUDE 
DIRECTLY INTO THE STARTUP.ASM 

1 ; THESE SYMBOLS CONTROL CONDITIONAL 

1 ; ASSEMBLY ELSEWHERE 

"HEADER" ; INCLUDE THE EQUATES AND 

STARTUP.ASM WHICH HAS THE -START 
LABEL AS ITS FIRST INSTRUCTION 

; WHEN STARTUP.ASM IS READY, IT 
PERFORMS A BSR MAIN AND RUNS YOUR 
CODE 

YOUR PROGRAM CODE HERE 

; END PROGRAMS WITH RETURN FROM 

; SUBROUTINE 



Now, examine the rest of the STARTUP.ASM source code. 
Note the source code's appearance. Semicolons set off com- 
ments; labels always appear in the first column of text; and 
unlabeled lines are always indented. Note the extensive use of 
macros to call Amiga kernel functions that make the code 
readable and short. 

EVENPC (EVEN Program Counter) is a macro that in- 
sures the next address used will be word-aligned in memory. 
Remember that word and long-word data must be on an even 
address, and whenever a string of bytes is set up (with a DC.B 
pseudo op), it may end on an odd address. Whenever an ad- 
dress must be even, and you're not certain it is, use the 
EVENPC macro. It's used extensively throughout listings in 
this book. It is not necessary to use it if you always declare 
even numbers of bytes, but that can be difficult with long 
character strings. 
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Remember that failure to insure word-alignment 
where it is necessary will cause the machine to crash. 



STARTUP.ASM also contains some strange labels, like 
PROC.MSGPORT, and WA.LOCK, with no apparent meaning. 
These are all named structure fields (or position offsets) — they 
have numerical equivalents in the equate files and refer to 
fields in structures. Although they seem to make no sense, be 
assured that they all have numerical equivalents. The assem- 
bler will know what they mean. 

Note, also, that after accomplishing entry to the operating 
system, the actual source code program is called as a subrou- 
tine named MAIN. That means that source code files should 
have a label called MAIN as the entry point. 

For simplicity, this STARTUP.ASM startup/ending code 
skips doing any Workbench message analysis. None of the 
programs in this book use Workbench messages. The code 
provided does make it possible to start programs that were 
made using STARTUP.ASM from the Workbench by double- 
clicking the mouse pointer on an icon. Simply copy a tool-type 
icon and give it the name of your finished program file. The 
parameters (the Tooltypes window and Comments window of 
the icon) are ignored by STARTUP.ASM. 

After program control returns from executing the MAIN 
subroutine, the STARTUP.ASM closes down the opened librar- 
ies and returns with whatever the MAIN code left in DO. If an 
error occurred during startup, a direct route is provided to exit 
with a system error code in DO. 

You can easily expand and modify the STARTUP.ASM to 
suit your needs. Add more libraries (for instance, the Timer li- 
brary or Icon library), remove unneeded libraries, or eliminate 
the Workbench portion if your program only runs from the CLI. 

Familiarize yourself with the STARTUP.ASM program 
now. As long as everything is operating properly, no further 
thought need be given to STARTUP.ASM. Note that your code 
file is usually named SOURCE and its entry point should be 
MAIN. At assembly, the assembler will always look for a file 
named SOURCE, which includes the STARTUP.ASM via the 
HEADER file. 
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Listing 14-1. STARTUP. ASM: The standard start/end routine for 
programs in this book. 

******************************** STARTUP. ASM BY DANIEL WOLF 

COPYRIGHT 1987 BY COMPUTEI BOOKS 

06/10/87 

; ERROR CODES 

CANTINITSYSTEM EQU 20 
CANTOPENWINDOW EQU 21 
CANTOPENSCREEN EQU 22 
CANTALLOCMEM EQU 23 
CANTOPENDEVICE EQU 24 

• »** SYSTEM STARTUP CODE *** 



_START 

MOVE.L SP,_STACK 

MOVE.L A0, COMMAND 

MOVE.L D0.CMDLEN 

SUBA.L A1.A1 

SYSLIB FINDTASK 

MOVE.L D0,_TASK 
NOWSTARTUP 

MOVE.L #l,ENDFROMWB 

MOVE.L D0.A2 

TST.L PROC.CLKA2) 

BEQ.S FROM_WB 

FROM_CLI 
MOVE.L #0,ENDFROMWB 
MOVE.L #l,ENDFROMCLI 
MOVE.L COMMAND, A0 
MOVE.L CMDLEN.D0 
CLR.B -KA0.D0.W) 
BSR OPENDOS 
DOSLIB INPUT 
MOVE.L D0.STDIN 
DOSLIB OUTPUT 
MOVE.L D0.STDOUT 
MOVE.L D0.STDERR 
BRA NOWDOMAIN 

FROM_WB 
BSR OPENDOS 

LEA PROC.MSSPORT(A2),A0 
SYSLIB WAITPORT 
LEA PROC . MSGPORT ( A2 ) , A0 
SYSLIB SETMSG 
MOVE.L D0.WBMSG 



;SAVE STACK POINTER 

;SAVE ADDRESS OF COMMAND STRING 

;SAVE LENGTH OF COMMAND STRING 

; CLEAR ADDRESS REGISTER Al 

;FIND ADDRESS OF THIS TASK'S TASK STRUCTURE 

;SAVE THE POINTER TO TASK STRUCTURE 

; ASSUME ITS FROM WB 

;A2 CONTAINS TASK STRUCTURE ADDRESS 

!IS THIS TASK A CLI PROCESS? 

;NO, ITS FROM WORKBENCH 

;DO THIS CODE IF FROM CLI 

; CLEAR A BYTE AT END OF COMMAND TAIL 

,-OPEN THE DOS LIBRARY, WE NEED IT 

. SETUP CURRENT CLI WINDOW AS INPUT FILE 

;AND AS OUTPUT FILE 
;AND AS ERROR FILE 
;NOW OPEN LIBS AND RUN USER CODE 

J DO THIS CODE IF FROM WORKBENCH 

iWAIT FOR THE WORKBENCH MESSAGE 

;SAVE POINTER TO THIS MESSAGE 



IFD WBC ;DOES USER WANT DEFAULT WB CONSOLE? 
DEFAULTCONSOLE 

MOVE.L #NEWCONSOLE,Dl 

MOVE.L #MODE NEWFILE.D2 

DOSLIB OPEN ~ .'OPEN A 'DEFAULT' CONSOLE 

MOVE.L D0.STDIN 

MOVE.L D0.STDOUT 

MOVE.L D0.STDERR 

BEQ _STARTERROR 
SETCONTASK ;THIS 

LSL.L *2,D0 

MOVE.L D0.A0 



•GIVE UP IF THE CONSOLE ISN'T THERE 
IS A BCPL POINTER 
; CONVERT IT TO 68000 ADDRESS 

ITS THE ADDRESS OF THE FILE HANDLE 



MOVE.L _TASK,A2 ; STRUCTURE FOR THE CONSOLE 

MOVE.L FH.TYPE(A0),PROC.CONSOLETASK(A2) ;TELL THE TASK ABOUT THE CONSOLE 

ENDC 

,*** H0W OPEN LIBRARIES AND RUN USER'S PROGRAM CODE 'MAIN' *** 

NOWDOMAIN 
BSR OPENLIBS 
BSR MAIN J BRANCH TO SOURCE PROGRAM'S 'MAIN' LABEL 
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TST.L ENDFROMWB 
BEQ _ERROR 
MOVE.L STDOUT.D1 
BEQ _ERROR 

DOSLIB CLOSE 



;IP WORKBENCH PROGRAM, CLOSE DEFAULT CONSOLE WINDOW 
;IF IT NEVER GOT OPENED, SKIP ITI 



;*** NOW CLEAN UP AND EXIT TO SYSTEM *** 



_ERROR 

MOVE.L D0,-(SP) 

TST.L WBMSG 

BEQ.S MORFINISH 

MOVE.L WBMSG, Al 

JUST REPLYMSG 
MORFINISH 

MOVE.L REMEMBERKEY, D0 

BEQ.S 2$ 

LEA REMEMBERKEY, A0 

MOVEQ.L #1,D0 

INTLIB FREEREMEMBER 
2$ 

MOVE.L _GFXBASE,D0 

BEQ.S 3? 

BSR CLOSELIB 
35 

MOVE.L _INTBASE,D0 

BEQ.S 45 

BSR _CLOSELIB 
45 

MOVE.L _MATHBASE,D0 

BEQ.S 55 

BSR CLOSELIB 
55 

MOVE.L _MATHTRANSBASE, 

BEQ.S 65 

BSR _CU)SELIB 
65 

MOVE.L _DOSBASE,D0 

BEQ.S 75 

BSR _CLOSELIB 
75 

MOVE.L (SP)+,D0 

MOVE.L _STACK,SP 

RTS 



RETURN HERE TO CLEAR THINGS UP AND EXIT 
HIDE D0 FOR A MOMENT ON STACK 
WAS THERE A WORKBENCH MESSAGE? 
NOPE 

REPLY THE MESSAGE 

GIVE BACK ANY 'REMEMBER' MEMORY ALLOCATED BY PROGRAM 



CLOSE ANY OPEN LIBRARIES 



GET BACK D0 FROM STACK 

RESTORE STACK POINTER 

EXIT BACK TO WHERE THIS PROGRAM CAME FROMI 



_STARTERROR 
MOVEQ #CANTINITSYSTEM,D0 
BRA _ERROR 

OPENLIB 
"MOVE.L #0,D0 
SYSLIB OPENLIBRARY 
RTS 

_CLOSELIB 
MOVE.L D0.A1 
SYSLIB CLOSELIBRARY 
RTS 

OPENDOS 
LEA _DOSNAME,Al 
BSR _OPENLIB 
MOVE.L D0,_DOSBASE 
BEQ _STARTERROR 
RTS 

OPENLIBS 
IFD GFX 

LEA _GFXNAME,A1 
BSR _OPENLIB 
MOVE.L D0,_GFXBASE 
BEQ _STARTERROR 
ENDC 
IFD INT 

LEA _INTNAME,A1 
BSR _OPENLIB 
MOVE.L D0,_INTBASE 



ropen the DOS library now 
?put pointer to name in AI 
; open it 

rcheck for successful open 
?0 means error 



;open all the libraries we need 



;and save their jump table pointers 



u 
u 

u 

Li 
L 
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BEQ _STARTERROR 

ENDC 

IFD FFP 

LEA _MATHNAME,A1 

BSR _OPENLIB 

MOVE.L D0, MATHBASE 

BEQ _STARTERROR 

ENDC 

IFD TRA 

LEA.L _MATHTRANSNAME,A1 

BSR _OPENLIB 

MOVE.L D0,_MATHTRANSBASE 

BEQ _STARTERROR 

ENDC 

RTS 

;*** STARTUP DATA STORAGE 



_STACK DC.L 
_TASK DC.L 
_DOSBASE DC.L 
_GFXBASE DC.L 
_INTBASE DC.L 
_MATHBASE DC.L 
_MATHTRANSBASE DC.L 
REMEMBERKEY DC.L 
COMMAND DC.L 
CMDLEN DC.L 
WBMSG DC.L 
STDIN DC.L 
STDOUT DC.L 
STDERR DC.L 
ENDFROMWB DC.L 
ENDFROMCLI DC.L 

EVENPC 
_DOSNAME DC.B 'dos. library' ,0 ; 

EVENPC 
_GFXNAME DC.B 'graphics. library ' ,0 

EVENPC 
_INTNAME DC.B ' intuition. library ' ,0 

EVENPC 
_MATHNAME DC.B 'mathf fp. library ' ,0 

EVENPC 
_MATHTRANSNAME DC.B ' ma thtrans. library ' 

EVENPC 
NEWCONSOLE 

DC.B 'CON:2O/20/400/100/PROGRAH I/O' 

EVENPC 



;optionally open MATHTRANS library 



temporary stack pointer storage 
pointer to this task structure 
pointer to DOS library jump table 

GRAPHICS 

INTUITION 

MATHFFP 

MATHTRANS 
program-wide ALLOCREMEMBER 'hook' 
address of CLI command string 
length of CLI command string 
address of WORKBENCH message, if any 
address of INPUT file 
address of OUTPUT file 
address of ERROR file 
= i if from WORKBENCH 
= 1 if from CLI 

these names are required by OPENLIBRARY 
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H AmigaDOS 

j The Amiga Disk Operating System (AmigaDOS) is the sim- 
plest level of Amiga programming. AmigaDOS provides the 
CLI system of keyboard interaction and command execution. 
Whenever you type a CLI command, AmigaDOS routines per- 
form the function. 

AmigaDOS and Machine Language Programming 

Machine language programs can call AmigaDOS routines, or 
use AmigaDOS to call other programs. One powerful 
AmigaDOS routine, EXECUTE, can execute any command in 
ASCII text. By using EXECUTE, your programs can operate 
other AmigaDOS functions like LIST, COPY, and CD. 

AmigaDOS also provides a console window, which pro- 
grams can use as an Input/Output (I/O) channel to the key- 
board and screen. By combining various AmigaDOS features, 
your programs can do almost anything a user could do. 

Some AmigaDOS routines are more specific to its role as 
a disk operating system (DOS). These include OPEN and 
CLOSE, for opening and closing files, respectively. AmigaDOS 
also has routines for file locking. The lock feature of 
AmigaDOS allows single files to be opened and read by sev- 
eral programs multitasking in the Amiga environment, or it 
can prevent more than one program from writing to a file 
(called write-access). Some sort of lock mechanism is required 
in multitasking systems with files. It would be unwise to have 
a file opened by two different tasks at once, which may alter 
the file in different ways. 

The uses of the LOCK structure and related functions 
(LOCK, UNLOCK, PARENTDIR, CREATEDIR, CURRENTDIR, 
and DUPLOCK), and many other specialized and advanced" 
features of AmigaDOS, are beyond the scope of this presenta- 
tion. The reader is directed to a text that focuses more directly 
on the CLI or AmigaDOS, such as AmigaDOS Developer's Man- 
ual from Commodore or AmigaDOS Manual from Bantam. The 
programs in this book use AmigaDOS for text I/O and com- 
mand execution only. 
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u 


Table 15-1 is a list of some AmigaDOS functions 


showing 


u 


their parameter requirements and register usage conventions. 




Table 15-1. AmigaDOS Library Functions Used in this Book 


u 


Name Description Parameters Registers 


Result 


CLOSE Close file File Handle Dl 






DELAY Delay How Long Dl 




u 


EXECUTE Execute a CLI command Command,Input,Output D1,D2,D3 


1/0 


INPUT Get input file None (CLI ONLY) 


File handle 




OPEN Open file Name,AccessMode D1,D2 


File handle 




OUTPUT Get output file None (CLI ONLY) 


File Handle 




READ Read from file File,Buffer,Length D1,D2,D3 


# read/0 




WRITE Write to file File,Bufter,Length D1,D2,D3 


# written/0 





AmigaDOS INPUT and OUTPUT Calls for CLI- 
Originated Programs 

Information in this section applies only to programs started 
from the CLI. 

When a program is started from the CLI by typing its 
name as a command, the program inherits the CLI window. 
STARTUP.ASM performs AmigaDOS INPUT and OUTPUT 
calls and saves the file pointers for just this purpose. They are 
saved in the variables called STDIN, STDOUT, and STDERR 
(which gets the same pointer as STDOUT). These variable 
names are holdovers from the C language. They stand for 
STandarD INput, STandarD OUTput, and STandarD ERRor, 
respectively. They're the names of files to be used for user in- 
put, output, and error messages. 

INPUT and OUTPUT calls to identify the CLI's input and out- 
put streams. Since the program was started from the CLI, a 
console-type file is already OPEN. Therefore STARTUP.ASM 
makes INPUT and OUTPUT calls to find the OPEN console 
file — namely the current CLI. If the program opens another 
file, there's no need to call INPUT or OUTPUT for that file. 
These functions only identify the CLI I/O streams for pro- 
grams started from a CLI. 

STARTUP.ASM always opens the AmigaDOS Library and 
performs the INPUT and OUTPUT functions for CLI-based 
programs. Your SOURCE file doesn't need to include these 
opening calls. The STDIN, STDOUT, and STDERR file point- 
ers are all directed to the CLI from which the program was 
called. The program can use these variables to help with text 
I/O. 
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Text output to the CLI: AmigaDOS WRITE. The sim- 
plest Amiga program can use the existing CLI window to dis- 
play messages and respond to user keyboard input. 

Listing 15-1 shows how to use the WRITE function in a 
program. The DOSPRINT macro takes two parameters: the ad- 
dress of a null-terminated ASCII text and the pointer to the 
OUTPUT file. STDOUT is used as a label for this file. 
DOSPRINT calls the WRITE function. The WRITE function 
takes three parameters: a pointer to the OUTPUT file (in Dl), 
a pointer to the text (in D2), and the length of the text (in D3). 

WRITE does not use null-terminated text. Rather, it oper- 
ates under another widely used protocol. You must inform 
WRITE of the number of characters to print. But, since null- 
terminated text is so convenient in most situations, the 
DOSPRINT macro is programmed to count the characters in a 
string until a byte is reached. Then it feeds the character 
count to WRITE. The alternative would be to count the charac- 
ters yourself, "by hand," and adjust the value every time a 
string is altered. You can get a closer look at the DOSPRINT 
macro in the MACROSASM file. 

Listing 15-1 is a program that outputs a few messages to 
the CLI using both the WRITE function and the DOSPRINT 
macro. 

Listing 15-1. CLIPRINT.ASM 

##(CLIPRINT.ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 

;09/10/87 

;THIS PROGRAM WILL ONLY WORK FROM THE CLI I I 

;THIS PROGRAM WILL CRASH IF STARTED FROM THE WORKBENCH I I 

BRA _START; BRANCH PAST INCLUDES TO FIRST LINE OF 
.•STARTUP. ASM WHICH HAS LABEL _START 

;WBC EQU 1 ;IF THIS LINE IS INCLUDED, STARTUP. ASM 
;WILL PROVIDE A CONSOLE WINDOW FOR WORKBENCH 
; STARTUP AND THE PROGRAM WON ' T CRASH I I 

INCLUDE "HEADER" 

MAIN ; REQUIRED ENTRY LABEL OF THE PROGRAM 

;USE WRITE FUNCTION TO DISPLAY MESSAGE 
MOVE.L STDOUT, Dl ; OUTPUT FILE HANDLE FOR CLI WINDOW INTO Dl 

MOVE.L #MESSAGE,D2 .-ADDRESS OF TEXT MESSAGE INTO D2 

MOVE.L #LEN1,D3 .-LENGTH OF MESSAGE (# CHARACTERS) INTO D3 

DOSLIB WRITE ;NOW CALL THE DOS LIBRARY 'WRITE' FUNCTION 

DOSPRINT STDOUT, #MESSAGE2 ;USE MACRO TO PRINT SECOND MESSAGE - EASIER? 

;»*» NOW EXIT TO STARTUP. ASM *** 

DONE 
ZERO D0 ;NO ERRORS, SO PLACE IN D0 AS RETURN CODE 

RTS .-RETURN TO 'CLEANUP' PORTION OF STARTUP. ASM 
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.*** D ATA STORAGE *** 

MESSAGE 
DC.B ' This is an example of printing text using AmigaDos WRITE ',10,10,0 
EVENPC 

LEN1 EQU *-MESSAGE 

MESSAGE2 
DC.B ' NOTE USE OF 10 AS A LINEFEED CHARACTER ',10 
DC.B ' AND TO END THE TEXT STRING', 10,0 
EVENPC 

LEN2 EQU "-MESSAGE2 

END 



u 
u 

u 

u 
u 



Reading the command line. Starting a program from the 
CLI sometimes involves typing more than just the program's 
name. It's common to follow the program name with a space 
and one or more parameters. 

Most CLI commands also work this way. For example, 
you can type DIR to obtain a listing of the current directory, or 
you can type DIR OPT A to obtain a more complete directory 
listing. The latter command contains two parameters for the 
DIR program (OPT and A). Your programs can read the com- 
mand line, too. 

The first few lines of the STARTUP.ASM program insure 
that any program using it as a beginning/ending shell will be 
able to read the command line. When the Amiga operating 
system starts a program from the CLI, the address of the first 
parameter on the command line is stored in register AO, and 
register DO contains the parameter's length. STARTUP.ASM 
preserves these registers in the variables COMMAND and 
CMDLEN, for use by the program. 

The program can refer to these variables and use them to 
read the command line. Once again, COMMAND is the ad- 
dress of the parameter following the command (OPT A in the 
command DIR OPT A), sometimes called the tail of the com- 
mand. CMDLEN contains the number of characters in the 
command tail (five in the example given). I " j 

Listing 15-2 shows a simple program that accepts com- >~~~ >! 

mand tails and prints them out. This program is only mean- 
ingful when started from the CLI. If the program is started 
from the Workbench, the variables COMMAND and CMDLEN 
will contain useless information. 
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Listing 15-2. CMDTAIL.ASM 

##;CMDTAIL.ASM BY DANIEL WOLF 
.•COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 
,•09/10/87 

BRA _START 

WBC EQU 1 ;MAKE SURE THERE'S A DOS FILE TO PRINT TO I 
;BY MAKING STARTUP. ASM OPEN ONE IF THE 
[PROGRAM IS CALLED FROM WORKBENCH 
;STDIN, STDOUT WILL BE CLI OR CONSOLE DEPENDING 
TON WHERE THE PROGRAM IS STARTED FROM 

INCLUDE "HEADER" 

MAIN ;THIS MUST BE THE LABEL OF THE PROGRAM 

DOSPRINT STDOUT, COMMAND [MACRO TO PRINT TEXT TO CLI OR CONSOLE WINDOW 

;THE TWO LABELS ARE DEFINED IN STARTUP. ASM 

MOVE.L #TICKSPERSECOND,Dl ;WAIT 4 SECONDS TO SEE IT 
ASL.L <2,D1 

DOSLIB DELAY 

;*** NOW EXIT TO STARTUP. ASM *** 

DONE 
ZERO D0 ;NO ERRORS, SO PLACE IN D0 

RTS ; RETURN TO 'CLEANUP' PORTION OF STARTUP. ASM 



Reading the keyboard. A program started from the CLI 
can use the CLI's open console file to read keyboard input 
from the user. Programming this operation is straightforward. 
The program must make a memory buffer available for the in- 
coming characters. 

To call the AmigaDOS READ function, three parameters 
are required: 

• A pointer to the open file 

• A pointer to the memory buffer 

• The number of characters to READ 

The READ function will accept incoming characters until: 

• The buffer fills 

• The specified number of characters is READ 

• A carriage return is received 

Listing 15-3 is a program that prints a message and then 
reads the user's reply, all within the CLI. 
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Listing 15-3. CLIREAD.ASM 

##;CLIREAD.ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 

(09/10/87 

BRA _START 

WBC EQU 1 [MAKE SURE THERE'S A DOS FILE TO PRINT TOl 
;BY MAKING STARTUP. ASM OPEN ONE IF THE 
{PROGRAM IS CALLED FROM WORKBENCH 
(STDIN, STDOUT WILL BE CLI OR CONSOLE DEPENDING 
[ON WHERE THE PROGRAM IS STARTED FROM 

INCLUDE "HEADER" 

MAIN [THIS MUST BE THE LABEL OF THE PROGRAM 

DOSPRINT STDOUT, ^MESSAGE ; MACRO TO PRINT TEXT TO CLI OR CONSOLE WINDOW 

MOVE.L STDIN, Dl [READ FROM STDIN (EITHER CLI OR CON:) 

MOVE.L #KEYBUFFER,D2 (TO KEYBUFFER DECLARED BELOW 

MOVE.L #80, D3 (MAX 80 CHARS OR TIL RETURN 

DOSLIB READ 

DOSPRINT STDOUT, #KEYBUFFER (PRINT IT BACK OUT 

MOVE.L #TICKSPERSECOND,Dl 
ASL.L #2,D1 
DOSLIB DELAY 

;*** NOW EXIT TO STARTUP. ASM *** 

DONE 
ZERO D0 ;NO ERRORS, SO PLACE IN D0 AS ERROR CODE 

RTS [RETURN TO 'CLEANUP' PORTION OF STARTUP. ASM 

(*** DATA STORAGE *** 

MESSAGE 
DC.B ' Type in your message (up to 80 chars.) and press RETURN ',10,10,0 
EVENPC 

KEYBUFFER DS.B 80 [STORAGE FOR 80 CHARACTER KEYBOARD READ BUFFER 

END 



Opening a File 

As you've seen, a program started from the CLI already has a 
file open for I/O — the CLI. There will be situations, however, 
when you'll want to open files directly. When a file is opened 
by the AmigaDOS OPEN function, the pointer returned in DO 
is called a file handle. It has one unusual property: It is not a 
true MC68000 address. It is a BCPL pointer. BCPL is a popular 
language in Great Britain. BCPL also happens to be the lan- 
guage used to write most of AmigaDOS. 

Files not on floppy disks. AmigaDOS permits you to 
open various kinds of files besides those on floppy disk. Here 
are some examples of file names you can open with AmigaDOS: 

• A file on a disk in drive 1: DF1:MESSAGEFILE 

• The printer: PRT: 

• A console I/O window: CON:10/10/400/100/MYCONSOLE 
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When the printer is opened as a file, you should only use 
it for output. When using a CON: file, the input will come 
from the keyboard, and output will go to the window. It's pos- 
sible to open other devices and file types. Read through the 
listings in this chapter as a guide to experimentation with 
other types of files. You'll find CON: and PRT: files used in 
the listings. The listing ASMINT.ASM involves some addi- 
tional examples of AmigaDOS file usage. 

The OPEN function requires two parameters: 

• A pointer to the text name of the file in register Dl 

• An access mode in register D2 

When OPEN is called, the parameters tell the Amiga 
whether to use an existing file or create a new one. The differ- 
ent modes for opening files are summarized in Table 15-2. 

Table 15-2. Access Modes 

Mode Value Meaning 

MODE-NEWFILE 1006 New file opened for writing only 
MODE-OLDFILE 1005 Old file opened for reading and 

writing 
MODE_READ WRITE 1004 New file opened for reading and 

writing 
MODE-READONLY 1005 Old file opened for reading and 

writing 

Register DO will contain a value of if the OPEN com- 
mand fails. Be sure to test for this error condition. 

Once a program is finished using a file, it should put the 
file's handle in register DO and call the CLOSE function. 

Listing 15-4 is DOSOPEN.ASM, a program that opens a 
file in the ramdisk and closes it. 

Listing 15-4. DOSOPEN.ASM 

##; DOSOPEN.ASM BY DANIEL WOLF 
[COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 
;09/10/87 

BRA _START; BRANCH PAST INCLUDES TO FIRST LINE OF 
;STARTUP.ASM WHICH HAS LABEL _START 
WBC EQU 1 

INCLUDE "HEADER", -BRING IN INCLUDES AND STARTUP. ASM 

MAIN ; REQUIRED ENTRY LABEL OF THE PROGRAM 

jTHIS TIME THE PROGRAM OPENS A RAM FILE TO WRITE TO 

MOVE.L #FILE,D1 [POINTER TO NAME OF RAM FILE 

MOVE.L #MODE_NEWFILE,D2 ;AS A NEW FILE 
DOSLIB OPEN 
TST.L D0 
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BEQ QUIT ; SORRY, CAN'T OPEN THE CONSOLE 

MOVE.L D0, RAMFILE ;GIVE OURSELVES AN OUTPUT PILE TO WRITE INTO 

;USE WRITE FUNCTION TO PUT A MESSAGE THERE 
MOVE.L RAMFILE.Dl ;OUTPUT FILE HANDLE FOR CONSOLE WINDOW INTO Dl 

MOVE.L #MESSAGE,D2 lADDRESS OF TEXT MESSAGE INTO D2 

MOVE.L #LEN1,D3 ; LENGTH OF MESSAGE (# CHARACTERS) INTO D3 

DOSLIB WRITE (NOW CALL THE DOS LIBRARY "WRITE' FUNCTION 

DOSPRINT STDOUT,*MESSAGE2 ;USE MACRO TO PRINT SECOND MESSAGE - EASIER? 
;THIS ONE GOES TO THE USER (STDOUT)I 

MOVE.L #TICKSPERSECOND,Dl 

ASL.L #1,D1 

DOSLIB DELAY,- DELAY 2 SECONDS TO SEE THIS STUFF 

;*** NOW FINISH UP, CLOSE FILE, AND EXIT TO STARTUP. ASM *** 

DONE 
MOVE.L RAMFILE.Dl 
DOSLIB CLOSE; WE OPENED A CONSOLE, SO WE NEED TO CLOSE IT I 

QUIT 
ZERO D0 ,-NO ERRORS, SO PLACE IN D0 AS RETURN CODE 

RTS ; RETURN TO 'CLEANUP' PORTION OF STARTUP. ASM 

.*** DATA STORAGE *** 

FILE 
DC.B •RAMlRAMFILE' 
EVENPC 

MESSAGE 
DC.B ' This is an example of printing TO A FILE using AmigaDos WRITE ',10,10,0 
EVENPC 

LEN1 EQU '-MESSAGE 

MESSAGE2 
DC.B 10,' RAMFILE created IN RAM DISK. It has a message waiting for you. ',10,0 
EVENPC 

LEN2 EQU *-MESSAGE2 

RAMFILE 
DC.L 0;FILE HANDLE OF RAMsRAMFILE AFTER IT IS OPENED 



The Console Window 

You've seen how programs started from the CLI inherit the 
CLI's console window for input and output. STARTUP.ASM 
automatically attaches the program's I/O streams to the CLI 
window, if the program starts from a CLI. 

But what if the program starts from the Workbench, in- 
stead? Your programs should provide for this possibility. The 
CLI window may not be available for sending or receiving 
user messages. 

The AmigaDOS CON: device (CONsole device) can sub- 
stitute for the CLI window, when necessary. The CON: device 
has its own special features. It need not always function as a 
CLI substitute. The STARTUP.ASM program has a built-in call 
to open a CON: device file for programs that start from the 
Workbench. It is controlled by conditional assembly through 
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PI the WBC (WorkBench Console) symbol (see the latter half of 
Chapter 9). If you define the WBC symbol, STARTUP.ASM 
will assemble the part that opens the CON: for Workbench 

ii programs. Listing 15-5 shows the part of STARTUP.ASM that 
■' opens the CON: window under control of the WBC condi- 
tional symbol. 

i I Listing 15-5. Part of STARTUP. ASM that opens CON: window for 
Workbench programs. 

## 

.•PORTION OF STARTUP.ASM WHICH SETS UP AMIGADOS INPUT AND OUTPUT PILE HANDLES 
;THIS ISN'T A COMPLETE PROGRAM, SO DON'T EVEN TRY TO ASSEMBLE AND LINK ITU 

PROM CLI ;DO THIS CODE IP FROM CLI 

MOVE.L #0,ENDFROMWB 
MOVE.L #l,ENDFROMCLI 

MOVE.L COMMAND, A0 ; CLEAR A BYTE AT END OF COMMAND TAIL 

MOVE.L CMDLEN.D0 
CLR.B -1(A0,D0.W) 

BSR OPENDOS ;OPEN THE DOS LIBRARY, WE NEED IT 

DOSLIB INPUT 

MOVE.L D0.STDIN ;SETUP CURRENT CLI WINDOW AS INPUT FILE 

DOSLIB OUTPUT 

MOVE.L D0.STDOUT ;AND AS OUTPUT FILE 

MOVE.L D0.STDERR ;AND AS ERROR FILE 

BRA NOWDOMAIN ; NOW OPEN LIBS AND RUN USER CODE 

FROM_WB ;DO THIS CODE IF FROM WORKBENCH 

BSR OPENDOS 

LEA PROC.MSGPORT(A2) ,A0 iWAIT FOR THE WORKBENCH MESSAGE 
SYSLIB WAITPORT 
LEA PROC . MSGPORT ( A2 ) , A0 
SYSLIB GETMSG 
MOVE.L D0.WBMSG ;SAVE POINTER TO THIS MESSAGE 

IFD WBC ;DOES USER WANT DEFAULT WB CONSOLE? 
DEFAULTCONSOLE 

MOVE.L #NEWCONSOLE,Dl 

MOVE.L #MODE_NEWFILE,D2 

DOSLIB OPEN ;OPEN A 'DEFAULT' CONSOLE 

MOVE.L D0.STDIN 

MOVE.L D0.STDOUT 

MOVE.L D0.STDERR 

BEQ.S _STARTERROR (GIVE UP IF THE CONSOLE ISN'T THERE 
SETCONTASK ;THIS IS A BCPL POINTER 

LSL.L #2,D0 ; CONVERT IT TO 68000 ADDRESS 

MOVE.L D0,A0 ;ITS THE ADDRESS OP THE FILE HANDLE 

MOVE.L _TASK,A2 ; STRUCTURE FOR THE CONSOLE 

MOVE.L FH. TYPE (A0), PROC. CONSOLETASK ( A2 ) ;TELL THE TASK ABOUT THE CONSOLE 

ENDC 

;*** NOW OPEN LIBRARIES AND RUN USER'S PROGRAM CODE 'MAIN' *** 

When a program opens a CON: device, it can perform in- 
put and output through the CON: window, instead of the CLI. 
When the program calls WRITE or uses the DOSPRINT 
macro, the output will go to the CON: window as if it were 
going to a CLI. CLI windows and CON: windows look and 
work alike for this simple kind of I/O. Listing 15-6 is a pro- 
gram that does simple text I/O. If the program is started from 
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a CLI, the messages will appear in the CLI window. If it starts 
from the Workbench, a CON: file window is opened (via the 
call built into STARTUP.ASM) and the messages will be 
printed there, instead. 

Listing 15-6. CONSOLE.ASM: Console from STARTUP.ASM 

##; CONSOLE. ASM BY DANIEL WOLF 
.•COPYRIGHT 1987 BY COMPUTE I PUBLICATIONS 
,-09/10/87 

BRA _START; BRANCH PAST INCLUDES TO FIRST LINE OF 
; STARTUP. ASM WHICH HAS LABEL _START 

INCLUDE "HEADER"; BRING IN INCLUDES AND STARTUP.ASM 

MAIN ; REQUIRED ENTRY LABEL OF THE PROGRAM 

[THIS TIME THE PROGRAM OPENS ITS OWN CONSOLE 

MOVE.L #CONSOLE,D1 jPOINTER TO NAME OF CONSOLE FILE 

MOVE.L #MODE_NEWFILE,D2 ;AS A NEW FILE 
DOSLIB OPEN 
TST.L D0 

BEQ QUIT ; SORRY, CAN'T OPEN THE CONSOLE 

MOVE.L D0.STDOUT ;GIVE OURSELVES AN OUTPUT FILE TO WRITE INI 
;STDOUT LABEL IS IN THE STARTUP.ASM FILE I 

;USE WRITE FUNCTION TO DISPLAY MESSAGE 
MOVE.L STDOUT.D1 ,-OUTPUT FILE HANDLE FOR CONSOLE WINDOW INTO Dl 

MOVE.L #MESSAGE,D2 .-ADDRESS OF TEXT MESSAGE INTO D2 

MOVE.L #LEN1,D3 ;LENGTH OF MESSAGE (# CHARACTERS) INTO D3 

DOSLIB WRITE [NOW CALL THE DOS LIBRARY 'WRITE' FUNCTION 

DOSPRINT STDOUT,#MESSAGE2 [USE MACRO TO PRINT SECOND MESSAGE - EASIER? 

MOVE.L #TICKSPERSECOND,Dl 

ASL.L #2,D1 

DOSLIB DELAY; DELAY 4 SECONDS TO SEE THIS STUFF 

;*** NOW FINISH UP, CLOSE WINDOW, AND EXIT TO STARTUP.ASM *** 

DONE 
MOVE.L STDOUT.D1 
DOSLIB CLOSE.-WE OPENED A CONSOLE, SO WE NEED TO CLOSE IT1 

QUIT 
ZERO D0 ;N0 ERRORS, SO PLACE IN D0 AS RETURN CODE 

RTS [RETURN TO 'CLEANUP' PORTION OF STARTUP.ASM 

[*** DATA STORAGE *** 

CONSOLE 
DC.B 'CON:10/10/500/90/EASY CONSOLE' 
EVENPC 

MESSAGE 
DC.B ' This is an example of printing text using AmigaDos WRITE ',10,10,0 
EVENPC 

LEN1 EQU "-MESSAGE 

MESSAGE2 
DC.B ' NOTE USE OF 10 AS A LINEFEED CHARACTER ',10 
DC.B ' AND TO END THE TEXT STRING', 10,0 
EVENPC 

LEN2 EQU *-MESSAGE2 
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The CON: file window's keyboard interaction can be quite 
simple. The CON: file normally returns ASCII characters. A 
variation on the CON: file window is called RAW:. RAW: win- 
dows can read the keyboard as well, but the input is in raw 
form instead of ASCII characters. You'll use the RAW: win- 
dow for input when you need to interpret individual key- 
strokes that aren't ASCII (function keys, for instance). See the 
Amiga ROM Kernel Reference Manual: Libraries and Devices for 
detailed information on the kinds of keyboard interpretations 
available with CON: and RAW:. 

Calling Other Programs with EXECUTE 

The EXECUTE function puts all the power of AmigaDOS 
within your program's reach. EXECUTE accepts a CLI com- 
mand or program name (with parameters) and executes it as if 
it were typed into a CLI window. 

It's easy to confuse this DOS EXECUTE function with the 
CLI command of the same name. They aren't the same. DOS 
EXECUTE is really the same as the CLI RUN command. If you 
wish the EXECUTE function to operate a command file (like 
CLI's EXECUTE) it's equivalent to typing: 

RUN EXECUTE 'COMMANDFILENAME' 

This confusion is the result of a poorly named function. It 
would have been less confusing if the AmigaDOS EXECUTE 
function were named RUN to match its CLI equivalent. The 
AmigaDOS EXECUTE function actually calls the CLI RUN 
command to do its job. The RUN command must be in either 
the current or command (C) directory, or the EXECUTE func- 
tion will fail. 

You can EXECUTE DELETE, CD, LIST, and other CLI 
commands. You can even run the ASM command (which is 
how the ASMINT program works). 

The EXECUTE function, requires three parameters: 

• A pointer to the null-terminated text of the CLI command 
string in register DO 

• An input file handle in register Dl 

• An output file handle in register D2 

The file handles in the last two parameters are usually the 
file handles of the CLI or CON: window currently in use. 
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If the command to be EXECUTED has any chance of 
causing read or write operations, the last two parameters 
are absolutely necessary. If a command tries to write 
without an output file handle, the Amiga will crash. 
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Listing 15-7 shows an example of the use of the EXE- 
CUTE function. It uses the existing CLI or CON: window (de- 
pending on how the program was started) as I/O for the 
EXECUTE. 

Listing 15-7. DOSEXEC.ASM 

##,-DOSEXEC.ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 

(09/10/87 

BRA _START 

WBC EQU 1 ;MAKE SURE THERE'S A DOS PILE TO PRINT TO I 
;BY MAKING STARTUP. ASM OPEN ONE IF THE 
; PROGRAM IS CALLED FROM WORKBENCH 
jSTDIN, STDOUT WILL BE CLI OR CONSOLE DEPENDING 
)ON WHERE THE PROGRAM IS STARTED FROM 

INCLUDE "HEADER" 

MAIN ;THIS MUST BE THE LABEL OF THE PROGRAM 

MOVE.L #EXECOMMAND,Dl 

ZERO D2 ;MAKE INPUT = OR THE CONSOLE WON'T CLOSE 1 
MOVE.L STDOUT.D3 ;EITHER CLI OR CONSOLE (IF FROM WB) 
DOSLIB EXECUTE 

;*** NOW EXIT TO STARTUP. ASM *** 

DONE 
ZERO D0 ;NO ERRORS, SO PLACE IN D0 

RTS ; RETURN TO 'CLEANUP' PORTION OF STARTUP. ASM 

EVENPC 

EXECOMMAND 
DC.B 'LIST',0 
EVENPC 

END 
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CHAPTER 16 

Intuition and Windows 



Intuition is the name of the Amiga's user interface. It consists of 

• Graphic windows (as opposed to the all-text console win- 
dows available through AmigaDOS) 

• Mouse-activated drop-down menus 

• Mouse-activated gadgets that act as buttons and sliders 

• Keyboard interaction string gadgets 

• Requester yes/no/continue choice windows. 

Before beginning to experiment with machine language 
and Intuition, it will be necessary to prepare an equate file to 
define symbols used in Intuition. The programs in this chapter 
require the INTEQUATES.ASM file (Listing 16-1), which con- 
tains the numeric definitions of library function offset ad- 
dresses, and field offsets, and so on. Enter this file with the 
EMACS text editor, according to the procedures in Organizing 
Development Files (steps 9 and 10). Using EMACS, save this 
file as: 

DEVS:RAMIT/INCLUDES/INTEQUATES.ASM 
Listing 16-1. INTEQUATES.ASM 

.**...**. INTEQUATES.ASM 

I COPYRIGHT 1988 COMPUTE! Publications 

.•03/24/87 

;*** INTUITION CONSTANTS, ROUTINE OFFSETS, AND STRUCTURE OFFSETS 

ACTIVATE EQU $1000 
ACTIVEWIHDOW EQU 540000 
ALTKEYMAP EQU ?1000 
AUTOKNOB EQU 51 

BACKDROP EQU 5100 
BEEPING EQU 520 
BOOLGADGET EQU 51 

.**• BORDER STRUCTURE OFFSETS 

BORD.BACKPEH EQU 55 
BORD. COUNT EQU 57 
BORD.DRAWMODE EQU 56 
BORD.FRONTPEN EQU 54 
BORD.LEFTED6E EQU 50 
BORD. NEXT EQU 5C 
BORD.TOPEDGE EQU 52 
BORD.XY EQU 58 
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BORDERLESS EQU 5800 
BOTTOMBORDER EQU $80 

CHECKED EQU $100 

CHECKIT EQU $1 

CLOSE EQU $80 

CLOSEWINDOW EQU $200 

COMMSEQ EQU $4 

CUSTOM EQU $40 

CUSTOMBITMAP EQU $40 

CUSTOMSCREEN EQU $F 

DELTAMOVE EQU $100000 
DISKINSERTED EQU $8000 
DISKREMOVED EQU $10000 

ENDGADGET EQU $4 

FOLLOWMOUSE EQU $8 

FREEHORIZ EQU $2 
FREEVERT EQU $4 

;**» GADGET STRUCTURE OFFSETS 

GADG. ACTIVATION EQU $E 
GADG. FLAGS EQU $C 
GADG. HEIGHT EQU $A 

GADG. ID EQU $26 
GADG.LEFTEDGE EQU $4 
GADG.HUTUALEXCLUDE EQU $1E 
GADG. NEXT EQU $0 
GADG. RENDER EQU $12 

GADG.SELECTRENDER EQU $16 
GADG.SPECIALINFO EQU $22 
GADG. TEXT EQU $1A 
GADG.TOPEDGE EQU $6 
GADG. TYPE EQU $10 
GADG.USERDATA EQU $28 
GADG. WIDTH EQU $8 



GADGBACKFILL 




EQU 


$1 


GADGDISABLED 




EQU 


$100 


GADGET0002 


EQU 


$2 






GADGETDOWN 


EQU 


$20 






GADGETTYPE 


EQU 


$FC00 




GADGETUP 


EQU 


$40 






GADGHBOX 


EQU 


$1 






GADGHCOMP 


EQU 


$0 






GADGHIGHBITS 




EQU 


$3 


GADGHIMAGE 


EQU 


$2 






GADGHNONE 


EQU 


$3 






GADGIMAGE 


EQU 


$4 






GADG IMMEDIATE 




EQU 


$2 


GIMMEZEROZERO 




EQU 


$400 


GRELBOTTOM 


EQU 


$8 






GRELHEIGHT 


EQU 


$40 






GRELRIGHT 


EQU 


$10 






GRELWIDTH 


EQU 


$20 






GZZGADGET 


EQU 


$2000 




HIGHBOX 


EQU 


$80 






HIGHCOMP 


EQU 


$40 






HIGHFLAGS 


EQU 


$C0 






HIGHIMAGE 


EQU 


$0 






HIGHITEM 


EQU 


$2000 




HIGHNONE 


EQU 


$C0 







u 
u 
u 
u 






;*** INTUIMESSAGE STRUCTURE OFFSETS 

IM. CLASS EQU $14 
IM.CODE EQU $18 
IM.IADDRESS EQU $1C 

IM.IDCMPWINDOW EQU $2C 
IM. MESSAGE EQU $0 
IM. MICROS EQU $28 
IM.MOUSEX EQU $20 
IM. MOUSEY EQU $22 
IM. QUALIFIER EQU $1A 
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IM. SECONDS EQU $24 
IM.SPECIALLINK EQU $30 

INACTIVEWINDOW EQU $80000 
INREQUEST EQU $4000 
INTUITICKS EQU $400000 
ISDRAWN EQU $1000 

.*** INTUITEXT STRUCTURE OFFSETS 



IT.BACKPEN 


EQU 


$1 






IT.DRAWMODE 






EQU 


$2 


IT. FONT 


EQU 


$8 






IT . FRONTPEN 






EQU 


$0 


IT.LEFTEDGE 






EQU 


$4 


IT. NEXT 


EQU 


$10 






IT. PAD 






EQU 


$3 


IT. TEXT 


EQU 


$c 






IT.TOPEDGE 


EQU 


$6 






ITEMENABLED 






EQU 


$10 


ITEMTEXT 


EQU 


$2 






KNOBHIT 


EQU 


$100 




KNOBHMIN 


EQU 


$6 






KNOBVHIN 


EQU 


$4 







LEFTBORDER EQU $20 

;*** INTUITION SUBROUTINE LIBRARY OFFSETS (PARTIAL LIST FROM AMIGA. LIB) 



LVO.ADDGADGET 




EQU $FFFFFFD6 


LVO . ALLOCREMEMBER 


EQU 


SFFFFFE74 


LVO.AUTOREQUEST 


EQU 


$FFFFFEA4 


LVO . CLEARDMREQUEST 


EQU 


SFFFFFFD0 


LVO . CLEARMENUSTRI P 


EQU 


SFFFFFFCA 


LVO.CLOSESCREEN 


EQU 


SFFFFFFBE 


LVO.CLOSEWINDOW 


EQU 


5FFFFFFB8 


LVO . CLOSEWORKBENCH 


EQU 


SFFFFFFB2 


LVO.DISPLAYBEEP 


EQU 


SFFFFFFA0 


LVO.DRAWBORDER 




EQU $FFFFFF94 


LVO.DRAWIMAGE 




EQU $FFFFFF8E 


LVO.ENDREQUEST 




EQU $FFFFFF88 


LVO . FREEREMEMBER 


EQU 


$FFFFFE68 


LVO . INTUITEXTLENGTH 




EQU $FFFFFEB6 


LVO.MODIFYIDCMP 


EQU 


$FFFFFF6A 


LVO.MODIFYPROP 




EQU $FFFFFF64 


LVO.MOVESCREEN 




EQU $FFFFFF5E 


LVO.MOVEWINDOW 




EQU $FFFFFF58 


LVO.OFFGADGET 




EQU $FFFFFF52 


LVO.OFFMENU 




EQU $FFFFFF4C 


LVO.ONGADGET 




EQU $FFFFFF46 


LVO.ONMENU 


EQU 


5FFFFFF40 


LVO . OPENSCREEN 




EQU $FFFFFF3A 


LVO.OPENWINDOW 




EQU $FFFFFF34 


LVO . OPENWORKBENCH 


EQU 


$FFFFFF2E 


LVO.PRINTITEXT 




EQU $FFFFFF28 


LVO . REFRESHGADGETS 


EQU 


$FFFFFF22 


LVO . REMOVEGADGET 


EQU 


$FFFFFF1C 


LVO.REPORTMOUSE 


EQU 


$FFFFFF16 


LVO. REQUEST 




EQU $FFFFFF10 


LVO . SCREENTOBACK 


EQU 


$FFFFFF0A 


LVO . SCREENTOFRONT 


EQU 


SFFFFFF04 


LVO . SETDMREQUEST 


EQU 


SFFFFFEFE 


LVO . SETMENUSTRI P 


EQU 


SFFFFFEF8 


LVO . SETWINDOWTITLES 




EQU $FFFFFEEC 


LVO . SHOWTITLE 




EQU $FFFFFEE6 


LVO.SIZEWINDOW 




EQU $FFFFFEE0 


LVO . VIEWPORTADDRESS 




EQU $FFFFFED4 


LVO . WINDOWTOBACK 


EQU 


SFFFFFECE 


LVO.WINDOWTOFRONT 


EQU 


SFFFFFEC8 


MAXBODY EQU $FFFF 




MAXPOT 


EQU 


$FFFF 



MENU STRUCTURE OFFSETS 
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MENU.BEATX EQU $1A 

MENU.BEATY EQU SIC 

MENU.FIRSTITEM EQU 512 

MENU. FLAGS EQU $C 

MENU. HEIGHT EQU ?A 

MENU.JAZZX EQU $16 

MENU. JAZZY EQU $18 

MENU . LEFTEDGE EQU $4 

MENU. NAME EQU $E 

MENU. NEXT EQU $0 

MENU.TOPEDGE EQU $6 

MENU. WIDTH EQU $8 

MENUCANCEL EQU $2 
MENUDOWN EQU $69 
MENUENABLED EQU $1 
MENUHOT EQU $1 
MENUNULL EQU $FFFF 
MENUPICK EQU $100 
MENUSTATE EQU $8000 
MENUTOGGLE EQU $8 
MENUTOGGLED EQU $4000 
MENUUP EQU $E9 

MENUVERIFY EQU $2000 
MENUWAITING EQU $3 



u 
u 
u 
u 
u 



. *** 



MENUITEM STRUCTURE OFFSETS 



MI. COMMAND EQU $1A 
MI. FLAGS EQU $C 
MI. HEIGHT EQU $A 
MI.ITEMFILL EQU $12 
MI. LEFTEDGE EQU $4 
MI.MUTUALEXCLUDE EQU $E 
MI. NEXT EQU $0 
MI.NEXTSELECT EQU $20 
MI. PAD EQU $1B 

MI.SELECTFILL EQU $16 
MI.SUBITEM EQU $1C 
MI.TOPEDGE EQU $6 
MI. WIDTH EQU $8 

MI DRAWN EQU $100 
MOUSEBUTTONS EQU $8 
MOUSEMOVE EQU $10 

NEWPREFS EQU $4000 
NEWSIZE EQU $2 
NOCAREREFRESH EQU $20000 

.*** NEWWINDOW STRUCTURE OFFSETS 



NW. BITMAP EQU 


$22 






NW.BLOCKPEN 




EQU 


$9 


NW. CHECKMARK 




EQU 


$16 


NW.DETAILPEN 




EQU 


$8 


NW.FIRSTGADGET 




EQU 


$12 


NW. FLAGS EQU 


$E 






NW. HEIGHT EQU 


$6 






NW.IDCMPFLAGS 




EQU 


$A 


NW . LEFTEDGE 




EQU 


$0 


NW.MAXHEIGHT 




EQU 


$2C 


NW.MAXWIDTH 




EQU 


$2A 


NW.MINHEIGHT 




EQU 


$28 


NW.MINWIDTH 




EQU 


$26 


NW. SCREEN EQU 


$1E 






NW. TITLE EQU 


$1A 






NW.TOPEDGE EQU 


$2 






NW.TYPE EQU 


$2E 






NW. WIDTH EQU 


$4 







u 
u 



OTHER_REFRESH EQU $C0 

.»»* pRQPINFO STRUCTURE OFFSETS '' 



PI.CHEIGHT EQU $C 
PI.CWIDTH EQU $A 
PI. FLAGS EQU $0 
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PI.HORIZBODY 




EQU 


56 


PI.HORI2POT 




EQU 


52 


PI.HPOTRES EQU 


SE 






PI.LEFTBORDER 




EQU 


512 


PI.TOPBORDER 




EQU 


514 


PI.VERTBODY 




EQU 


58 


PI.VERTPOT EQU 


$4 






PI.VPOTRES EQU 


510 






POINTREL EQU 


SI 






PREDRAWN EQU 


52 






PROPBORDERLESS 




EQU 


58 


PROPGADGET EQU 


S3 







RAWKEY EQU 5400 

REFRESHBITS EQU SC0 

REFRESHWINDOW EQU 54 

RELVERIFY EQU 51 

REQACT1VE EQU 52000 

REQCLEAR EQU 51000 

REQGADGET EQU 51000 
REQOFFWINDOW EQU 51000 
REQSET EQU 580 

REQVERIFY EQU 5800 
RIGHTBORDER EQU 510 

RMBTRAP EQU 510000 

SCREENTYPE EQU 5F 
SCRGADGET EQU 54000 

.*** SCREEN STRUCTURE OFFSETS (PARTIAL LIST) 

SCRN.MOUSEX EQU 512 

SCRN. MOUSEY EQU 510 

SCRN.RASTPORT EQU 554 

SCRN. VIEWPORT EQU S2C 

SCRN. TITLE EQU 516 

SCRN. WIDTH EQU 5C 

SCRN. HEIGHT EQU 5E 

SELECTDOWN EQU 568 

SELECTED EQU 580 

SELECTUP EQU 5E8 

SHOWTITLE EQU 510 

,**« STRINGINFO STRUCTURE OFFSETS 

SI.ALTKEYMAP EQU 520 
SI. BUFFER EQU 50 
SI.BUFFERPOS EQU 58 
SI. CLEFT EQU 514 
SI.CTOP EQU 516 
SI.DISPCOUNT EQU 512 
SI.DISPPOS EQU SC 
SI.LAYERPTR EQU 518 

SI.LONGINT EQU 51C 
SI.MAXCHARS EQU $A 

SI.NUMCHARS EQU 510 

SI.UNDOBUFFER EQU 54 
SI.UNDOPOS EQU 5E 

SIMPLE_REFRESH EQU 540 

,«»* VARIOUS STRUCTURE SIZES 

SIZE.BORD EQU 510 

SIZE.GADG EQU 52C 

SIZE.IM EQU 534 

SIZE.IMAG EQU 514 

SIZE. IT EQU 514 

SIZE. MENU EQU S1E 

SIZE. MI EQU 522 

SIZE.NS EQU 520 

SIZE.NW EQU 530 

SIZE. PI EQU 516 

SIZE.REQ EQU 570 

SIZE. SCRN EQU 515C 

SIZE. SI EQU 524 
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SIZEBBOTTOM EQU 520 

SIZEBRIGHT EQU 510 
SIZEVERIFY EQU $1 
SIZING EQU $10 

.*** STARTUP MESSAGE OFFSETS 



SM.ARGLIST EQU 


524 






SM. MESSAGE EQU 


50 






SM.NUMARGS EQU 


51C 






SM. PROCESS EQU 


514 






SM. SEGMENT EQU 


518 






SM.TOOLWINDOW 




EQU 


520 


SMART REFRESH 




EQU 


50 


STRGADGET EQU 


54 






STRINGCENTER 




EQU 


5200 


STRINGRIGHT 




EQU 


5400 


SUPER BITMAP 




EQU 


580 



u 
u 

I i 
LJ 

Li 
LJ 



SYSGAGET EQU 58000 
SYSREQUEST EQU 54000 

TOGGLESELECT EQU 5100 
TOPBORDER EQU 540 

VANILLAKEY EQU 5200000 

WA.LOCK EQU 50 
HA. NAME EQU 54 
WBENCHMESSAGE EQU 520000 
WBENCHSCREEN EQU 51 
WBENCHWINDOW EQU 52000000 

,*** WINDOW AND IDCMP FLAGS DEFINITIONS 

WINDOWACTIVE EQU 52000 

WINDOWCLOSE EQU 58 

WINDOWDEPTH EQU 54 
WINDOWDRAG EQU $2 

WINDOWREFRESH EQU 51000000 

WINDOWSIZING EQU 51 

WINDOWTICKED EQU 54000000 

.*** WINDOW STRUCTURE OFFSETS (PARTIAL LIST) 

WW. FLAGS EQU 518 
WW. HEIGHT EQU 5 A 
WW.IDCMPFLAGS EQU 552 
WW.MOUSEX EQU 5E 
WW. MOUSEY EQU 5C 
WW.RPORT EQU 532 
WW.SCREENTITLE EQU 568 
WW. TITLE EQU 520 
WW.USERPORT EQU 556 

WW.WINDOWPORT EQU 55A 
WW.WSCREEN EQU $2E 
WW. WIDTH EQU 58 
WW.TOPEDGE EQU 56 
WW.LEFTEDGE EQU 54 



Intuition is a powerful resource. If you've used commercial j j 
software packages for the Amiga, you're already familiar with '- — ' 
the use of menus, gadgets, and so on. This interaction is sup- 
ported by a family of routines in the Intuition library. A se- j j 
lected list of the Intuition library functions is presented in ' — ' 
Table 16-1 below. By mastering their use, your own programs 
can have a professional appearance. Because Intuition win- j I 
dows are the key to Intuition's other features, they'll be exam- L — ' 
ined first. 

U 
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The following Intuition library functions are those used in 
the programs in this book. For complete list and descriptions, 
see the Amiga Intuition Reference Manual, Appendix A, pages 
1-79. 

Table 16-1. Intuition Library Functions 

Gadget Functions 

(See list of abbreviations below.) 











Result 




Function Name 


Parameters 


Registers 


Succeed/Fail 




ADDGADGET 


(Win, Gad, List Position) 


A0,A1,D0 


Position added 




REMOVEGADGET 


(Win,Gad) 


A0,A1 


Position 
removed 




MODIFYPROP 


(Gad,Win,(Req),Flags,HP, 
VP,HB,VB) A0-A2,D0-D4 








ONGADGET 


(Win,Gad,(Req) ) 


A0-A2 






OFFGADGET 


(Win,Gad,(Req) ) 


A0-A2 






REFRESHGADGETS 


(Gad,Ptr,(Req)) 

If Gadget is not in a requester, 

(Req) = 


A0-A2 






Memory Allocation 






Result 




Function Name 


Parameters 


Registers 


Succeed/Fail 




ALLOCREMEMBER 


(RememberKey,Size,Flags) 


A0,D0,D1 


Pointer/0 




FREEREMEMBER 


(RememberKey,ReallyForget) 
If ReallyForget = 1, then free 
entire Remember list and 
memory buffers 
If ReallyForget = 0, then free 
only the Remember list 


A0,D0 






Requester Functions 






Result 




Function Name 


Parameters 


Registers 


Succeed/Fail 


n 


AUTOREQUEST 


(Win,BText,PText,NText,PFlg, 








NFlg,Width,Height) 


A0-A3,D0-D3 


Win/ALERT 




BUILDSYSREQUEST 


(Win,BText,PText,NText,Flg, 






n 

1 




Width,Height) 


A0-A3,D0-D2 


Win/ALERT 


ENDREQUEST 


(Req,Win) 


A0,A1 




1 1 


REQUEST 


(Req, Win) 


A0,A1 


1/0 




Menu Functions 








n 








Result 


Function Name 


Parameters 


Registers 


Succeed/Fail 




CLEARMENUSTRIP 


(Win) 


A0 




n 


SETMENUSTRIP 


(Win,Menu) 


A0,A1 




n 
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INTUITEXT Functions 

Function Name Parameters 
INTUITEXTLENGTH (IText) 


Registers 
AO 


Result 

Succeed/Fail 
pixel length 


u 


PRINTITEXT 


(RastPort,IText,Left,Top) 


A0,A1,D0,D1 




Screen Functions 










Function Name 
CLOSESCREEN 


Parameters 
(Scr) 


Registers 
AO 


Result 
Succeed/Fail 


u 


DISPLAYBEEP 


(Scr) 


AO 






OPENSCREEN 


(NewScreen Structure) 


AO 


Scr/0 




SHOWTITLE 


(Scr,Showit) 

If Showit = 1, then title will 

be shown 

If Showit = 0, then title will 

not be shown 


A0,D0 






Window Functions 










Function Name 
CLOSEWINDOW 


Parameters 
(Win) 


Registers 
AO 


Result 
Succeed/Fail 




MODIFYIDCMP 


(Win,Flags) 


A0,D0 






MOVEWINDOW 


(Win,dx,dy) 


A0,D0,D1 






OPENWINDOW 


(NewWindow Structure) 


AO 


Win/0 




SIZEWINDOW 


(Win,dx,dy) 


A0,D0,D1 






VIEWPORTADDRESS 


(Win) 


AO 






WINDOWTOBACK 


(Win) 


AO 






WINDOWTOFRONT 


(Win) 


AO 







Abbreviations used in this Table 

Win Pointer to Window Structure 

Gad Pointer to Gadget Structure 

Req Pointer to Requester Structure 

Scr Pointer to Screen Structure 

xText Pointer to INTUITEXT Structure 

Pxxxx 'Positive' Text or Flags for Requester 

htxxxx 'Negative' Text or Flags for Requester 

HP Value to be stored in a Proplnfo HorizPot variable 

VP Value to be stored in a Proplnfo VertPot variable 

HB Value to be stored in a Proplnfo HorizBody variable 

VB Value to be stored in a Proplnfo VertBody variable 



Using Intuition Windows 

For the purpose of this discussion, the screen for all windows 
is the Workbench screen. Custom screens will be discussed 
later. 



U 
U 
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Here is the sequence of events that must take place in or- 
der to use an Intuition window: 



|"—j • Provide memory for a NEWWINDOW structure (48 bytes): 
' By declaring explicit storage (DS.n) 

By declaring a sequence of constants (DC.n) 
j — I By ALLOCATING 48 bytes 

' • Fill fields in the structure with data such as window width, 

height, type, and so on: 

Using MOVE instructions 

By using a special MACRO to define everything 

• Call the Intuition library function OPENWINDOW. If this 
function succeeds, it creates a window structure somewhere 
in memory and returns its address in register DO. If this func- 
tion fails, it returns a in DO. If successful, a new window is 
opened. 

• Now, you may eliminate the NEWWINDOW structure. Its 
function was only temporary. However, if you intend to open 
a series of windows, you may want to keep the NEW- 
WINDOW table to use again. 

• Now, perform any Intuition functions using the window, in- 
cluding printing text, sizing, or moving the window in front 
of or behind other windows in the same screen, and so on. 
Most of these functions require the address of the WINDOW 
structure (which was supplied by OPENWINDOW) in AO, 
and a call to an Intuition library function. For example: 



MOVEA.L WINDOW.A0 
INTLIB WINDOWTOFRONT 



PUT ADDRESS OF WINDOW STRUCTURE 

INAO 

MACRO CALL WINDOWTOFRONT 

ROUTINE 



1 Close the window when you finish using it. 

MOVEA.L WINDOW.A0 
INTLIB CLOSEWINDOW 



n 
n 

The CLOSEWINDOW gadget doesn't actually close a win- 
r _^ dow. All it does is send your program a message saying that 
j | the CLOSEWINDOW gadget was clicked. The program must 
still close the window. More about communications through 
, messages later. 

n 
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The NEWWINDOW Structure 

Assuming the program has either provided a memory area 
(using DS.B 48) or successfully allocated memory (using 
SYSLIB ALLOCMEM), you begin to create a window by plac- 
ing the pointer to the structure's memory area in address reg- 
ister AO (or any other convenient address register). Table 16-2 
takes a closer look at this structure to help determine which 
fields to fill. 

Table 16-2. The Intuition NEWWINDOW Structure 



Symbol: NW 






Size: 48 bytes ($30 bytes! 


1 




Field 








Size 


Name 


Offset Description 


Word 


NW.LEFTEDGE 





How many pixels from left edge 
of screen 


Word 


NW.TOPEDGE 


2 


How many pixels from top edge 

of screen 


Word 


NW.WIDTH 


4 


How many pixels wide 


Word 


NW.HEIGHT 


6 


How many pixels high 


Byte 


NW.DETAILPEN 


8 


Color register number for gad- 
gets and title 


Byte 


NW.BLOCKPEN 


9 


Color register number for block 
fills 


Long 


NW.IDCMPFLAGS 


10 


Bits control event 
communications 


Long 


NW.FLAGS 


14 


Bits control window standard 
gadgets 


Long 


NW.FIRSTGADGET 


18 


Pointer to your first gadget 
structure 


Long 


NW.CHECKMARK 


22 


Pointer to custom menu check- 
mark image 


Long 


NW.TITLE 


26 


Pointer to null-terminated text 

title 

Pointer to custom screen (if any) 


Long 


NW.SCREEN 


30 


Long 


NW.BITMAP 


34 


Pointer to custom bitmap (if 
any) 


Word 


NW.MINWIDTH 


38 


Minimum window width in 

pixels 

Minimum window height in 


Word 


NW.MINHEIGHT 


40 








pixels 


Word 


NW.MAXWIDTH 


42 


Maximum window width in 
pixels 



u 
u 
u 
u 
u 
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Field 

Size Name 

Word NW.MAXHEIGHT 
Word NW.TYPE 



Offset Description 

44 Maximum window height in 

pixels 
46 Type of screen 



A number of the fields in a NEWWINDOW structure 
(NW.SCREEN, NW.BITMAP, NW.FIRSTGADGET, and 
NW.CHECKMARK) are only used for exotic types of windows. 
They can be set to values. If the NEWWINDOW structure is 
allocated with MEMF_CLEAR, they will already be and can 
be ignored. 

You must insure that the fields are filled in with valid 
data, or else suffer the consequences. Numbers for 
NW. WIDTH, NW.HEIGHT, NW.LEFTEDGE, NW.TOPEDGE, 
NW.MAXHEIGHT, NW.MINHEIGHT, NW.MAXWIDTH, and 
NW.MINWIDTH should be inserted into these fields (they are 
all word-size). Typical values might be: 



NW.LEFTEDGE 


20 




NW.TOPEDGE 


20 




NW.WIDTH 


300 




NW.HEIGHT 


80 




NW.MAXWIDTH 


640 




NW.MAXHEIGHT 


200 




NW.MINWIDTH 


50 




NW.MINHEIGHT 


20 




And corresponding code for these values can use the MOVE 


instruction, as in the first example below: 






EXAMPLE METHOD OF FILLING 






A NEWWINDOW STRUCTURE 






EXAMPLE 1 






USING THE MOVE 






INSTRUCTION 






(ASSUMING THE BASE AD- 






DRESS OF THE NEWWINDOW 






STRUCTURE IS IN AO) 


MOVE.W 


#20,NW.LEFTEDGE(A0) 




MOVE.W 


#20,NW.TOPEDGE(A0) 




MOVE.W 


#300,NW.WIDTH(A0) 




MOVE.W 


#80,NW.HEIGHT(A0) 


(AND SO ON) 

EXAMPLE 2 

USING DC.X DIRECTIVES TO 

DECLARE PART OF A 
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NEWW1ND0W 



DC.W 
DC.W 

DC.W 
DC.W 



20 
20 
300 
80 



NEWWINDOW STRUCTURE 

LABELED ADDRESS OF THE 
BASE OF A NEWWINDOW 
STRUCTURE 



(AND SO ON) 



Other fields that can be filled without much deliberation 
are NW.DETAILPEN and NW.BLOCKPEN. Since the Work- 
bench screen is being used, you can place any number from 
0-3 in these fields. The number in the DETAILPEN field se- 
lects which of the four Workbench colors set in Preferences 
will be used for window details, like gadgets and title text. The 
number in the BLOCKPEN field selects which Workbench 
color will be used for block fills. 

The NW.TYPE field is filled with the word value 
WBENCHSCREEN, for the time being (all windows will use 
the Workbench screen). 

The NW. TITLE field is filled with a pointer to some null- 
terminated text for the window title. If you don't want a title, 
leave the value of in NW. TITLE. 

Listing 16-2 shows the methods used to fill the 
NEWWINDOW structure fields that will appear in a program 
named WINDOW1.ASM later on. A NEWWINDOW structure 
is in the source code data declarations of WINDOW1.ASM 
(see Listing 16-3). 

Listing 16-2. Declaring a Full NEWWINDOW Structure with DC* 



NEWWINDOW 




DC.W 


40 


DC.W 


IS 


DC.W 


300 


DC.W 


160 


DC.B 


2 


DC.B 


1 


DC.L 


CLOSEWINDOW 


DC.L 


WINDOWCLOSE 


DC.L 





DC.L 





DC.L 


TITLETEXT 



u 
u 
u 
u 
u 



LEFT 


u 


TOP 




WIDTH 




HEIGHT 

DETAILPEN 


u 


BLOCKPEN 




IDCMP - CAN RECEIVE THE 




'CLOSEWINDOW MESSAGE 


u 


FLAGS - WINDOW HAS THE 


'CLOSEWINDOW GADGET 




POINTER TO FIRST GADGET 




POINTER TO USER-DEFINED 


u 


CHECKMARK 


POINTER TO SOME TITLE TEXT, 




NULL-TERMINATED 






u 
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DC.L 





POINTER TO SOME CUSTOM SCREEN 




DC.L 





POINTER TO SOME CUSTOM BITMAP 




DC.L 


50 


MINIMUM WIDTH IF 'RESIZING' 
GADGET IS WORKING 




DC.L 


20 


MINIMUM HEIGHT 




DC.L 


640 


MAXIMUM WIDTH 




DC.L 


200 


MAXIMUM HEIGHT 




DC.L 


WBENCHSCREEN 


SYMBOLIC NAME OF TYPE OF SCREEN 


TITLETEXT 









DC.B 'HERE IS THE WINDOW TITLE',0 

Now you can concentrate on the two most complex fields. 

The NW.FLAGS field. One of the most flexible and com- 
plex things to master in working with Intuition windows is the 
use of the NW.FLAGS field of the NEWWINDOW structure. 
The NW.FLAGS field is a long word (32 bits) in which each 
bit controls a standard gadget (window size, window close, 
window drag, and others) or a window feature (such as refresh 
mode, borders on, borders off, and so on). 

In a program, individual bits of the NW.FLAGS field are 
ORed together to build up the NW.FLAGS data word. Here's a 
typical example: 

LEA NEWWINDOW.A0 ; PUT BASE ADDRESS OF STRUCTURE IN A0 
MOVE.L #WINDOWSIZING!WINDOWCLOSE!WINDOWDRAG,NW.FLAGS(A0) 

The second statement tells the assembler to use the ! as- 
sembler directive (which represents a logical OR) to combine 
flag bits for a window size gadget, window drag bar, and the 
window close gadget. There are many other possible combina- 
tions of flags. 

Table 16-3 lists the available gadgets and features, their 
bit designations and brief descriptions. You can combine them 
in your NEWWINDOW structure by using their symbolic 
names and the logical OR assembler directive (!), or write 
hexadecimal digits into your code representing desired com- 
binations of the bits. The latter method is not only more com- 
plicated, but will make your software harder to maintain; 
future software releases might change the bit positions of the 
flags. 



179 



Chapter 16 



Table 16-3. NW.FLAGS (NEWWINDOW FLAGS field) 

Function 

Adds window sizing gadget 
Adds window drag gadget 
Adds window depth gadget 
Adds window close gadget 
Makes size gadget fill right 
edge 

Makes size gadget fill bottom 
edge 

System automatically redis- 
plays uncovered parts 
Program must refresh uncov- 
ered parts 

Window refreshed from custom 
bitmap 

This windows stays behind all 
others 

Set if you need continuous re- 
ports of mouse movement 
Puts system gadgets in sepa- 
rate bitmap 
No window outline 
Turns window on when first 
opened 

Set by Intuition when window 
is active 

Setting this flag disables menu 
operations. Program receives 
normal MOUSEBUTTON 
events when the right mouse 
button is pressed. 
Set this flag if you don't want 
to receive refresh messages. 

It would be a good idea to experiment with the 
WINDOW1.ASM program (Listing 16-7) using different com- 
binations of NW.FLAG bits to see what effects they have in 
practice. The subroutine labeled MAKEAWINDOW uses one 
combination that is effective for many standard uses, but don't 
limit yourself to the structure in this subroutine. Some experi- 
menting may turn up a subroutine more suited to your specific 
needs. 



Name 

WINDOWSIZING 

WINDOWDRAG 

WINDOWDEPTH 

WINDOWCLOSE 

SIZEBRIGHT 


Hexadecimal 
Value 

$0001 

0002 

0004 

0008 

0010 


SIZEBBOTTOM 


0020 


SMART-REFRESH 


0000 


SIMPLE_REFRESH 


0040 


SUPER_BITMAP 


0080 


BACKDROP 


0100 


REPORTMOUSE 


0200 


GIMMEZEROZERO 


0400 


BORDERLESS 
ACTIVATE 


0800 
1000 


WINDOWACTIVE 


2000 


RMBTRAP 


10000 



NOCAREREFRESH 



20000 



u 
u 



u 
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The IDCMPFLAGS flag. The communications channel 
between Intuition and your window is the window's Intuition 
Direct Communications Message Port (IDCMP). IDCMPFLAGS 
is a long word. Each bit controls one aspect of event commu- 
nication with your program. 

Using IDCMPFLAGS, you can alert your program to such 
events as mouse-button presses (and/or releases). You may 
wish to receive a WINDOWCLOSE message when the user 
clicks a CLOSEWINDOW gadget. Each of these is considered 
an event and is communicated by an Intuition message 
(INTUIMESSAGES) to your program, if your window is active 
and the program requests a look at the messages. 

Intuition captures all keystrokes, mouse movements, 
mouse button events, disk insertions and removals, and many 
other events. Then, it sends messages to all Intuition programs 
that request them. 

If you set the appropriate flags, your program will be noti- 
fied when the specified event occurs. If you fail to set the cor- 
rect flags, your program will never know about certain 
external events like mouse movement. Here's a typical IDCMP 
flags setting: 

LEA NEWWINDOW.A0 

MOVE.L #CLOSEWINDOW!MENUPICK,NW.IDCMPFLAGS(A0) 

This arranges for your program to be notified of window close 
and menu events. Using this code will cause your program to 
be ignorant of all keystrokes and mouse movements. There 
will be more discussion of IDCMP FLAGS in Chapter 17. 

Listing 16-3 contains the WINDOWS. ASM include file for 
use with the subsequent programs in this chapter, and later 
chapters as well. It has a complete subroutine for opening a 
window (MAKEAWINDOW) and a macro (MAKEWIN), which 
can be used to perform much of the work of opening Intuition 
windows. Using EMACS or your favorite text editor, enter 
WINDOWSASM and save it with the name: 

DEVS:RAMIT/INCLUDES/WINDOWS.ASM 
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Listing 16-3. WINDOWS.ASM 

,*•*•*•*•******.*»*****.*.*»».,** WINDOWS.ASM BY DANIEL WOLF 

(COPYRIGHT 1987 BY COMPUTEI BOOKS 

;03/21/87 

MAKEWIN MACRO ; PARAMETERS 
LEA _THISTITLE,A0 
MOVE.L \1,(A0) 
MOVE.W #\2,D4 
MOVE.W #\3,D5 
MOVE.W #\4,D6 
MOVE.W #\5,D7 
BSR MAKEAWINDOW 
TST.L D0 
BEQ \6 
IFNC '\7' , ' ■ 
MOVE.L D0,\7 
EIJDC 
EN DM 

;NEW WINDOW STRUCTURE SUPPORT FOR USE WITH OPENWINDOW FUNCTION 

MAKEAWINDOW .'SUBROUTINE ENTER WITH D4=LEFT,D5=TOP,D6=WIDTH,D7=HEIGHT 

_THISTITLE=POINTER TO NULL-TERMINATED WINDOW TITLE 

MOVE.L #SIZE.NW,D0 ; ALLOCATE ONE NEWWINDOW'S WORTH OF MEMORY 

MOVE.L #MEMF_CLEARIMEMF_CHIP,D1;MAKING SURE ITS SET TO ZERO AND IN CHIPMEM 

SYSLIB ALLOCMEM ; ALLOCATE THIS MEMORY INDEPENDENT OF ALL ELSE 

TST.L D0 ;IF NOT SUCCESSFUL WE GET A ZERO BACK IN D0 

BEQ ERR_MAKEAWINDOWMEM 

MOVE.L D0, NEWWINDOW ;HANG ON TO THIS POINTER 

MOVE.L D0.A0 [WE CAN DELETE THIS MEMORY LATER 

MOVE.W D4,NW.LEFTEDGE(A0) ;A NEWWINDOW STRUCTURE CAN BE DE-ALLOCATED 

MOVE.W D5,NW.TOPEDGE(A0) ;AFTER IT HAS SERVED ITS PURPOSE 

MOVE.W D6,NW.WIDTH(A0) 

MOVE.W D7.NW. HEIGHT (A0) jNOW JUST FILL UP THE NEWWINDOW STRUCTURE 

MOVE.B #-l,NW.DETAILPEN(A0) ;-I IS ALWAYS BE HIGHEST COLOR REG # 

MOVE.B #-l,NW.BLOCKPEN(A0) ; REGARDLESS OF # COLORS AVAILABLE IN SCREEN 

MOVE.L _THISIDCMP,NW.IDCMPFLAGS(A0) ;PRE-SET IDCMP FLAGS 

MOVE.L THISFLAGS,NW.FLAGS(A0) ;PRE-SET WINDOWFLAGS 

MOVE.L JTHISTITLE,NW.TITLE(A0) ;POINTER TO TITLE TEXT 

MOVE.W #100,NW.MINWIDTH(A0) iREASONABLE MINIMUM WIDTH AND HEIGHT 

MOVE.W #2S,NW.MINHEIGHT(A0) 

MOVE.W #700,NW.MAXWIDTH(A0) .-MAXIMUM MAXIMUM WIDTH AND HEIGHT1 

MOVE.W #440,NW.MAXHEIGHT(A0) 

MOVE.W _THISTYPE,NW.TYPE(A0) fUSE THE SCREEN TYPE STORED IN JTHISTYPE 

MOVE.L _THISCREEN,NW.SCREEN(A0) ;ATTACH TO CUSTOM SCREEN OR (DEFAULT) 

INTLIB OPENWINDOW ;NOW OPEN IT1 

TST.L D0 

BEQ.S ERR MAKEAWINDOW ; POINTER TO WINDOW IN D0 

MOVE.L D07 THISWINDOW ; STASH POINTER FOR A SEC 

MOVE.L #SIZE.NW,D0 

MOVEA.L NEWWINDOW, Al 

SYSLIB FREEMEM ;FREE UP THE MEM USED FOR THE NEWWINDOW 

MOVE.L JTHISWINDOW, D0 ;NOW RETURN WITH POINTER TO WINDOW IN D0 

ZERO Dl ; CLEAR Dl, NO ERROR1 

RTS 

ERR MAKEAWINDOWMEM 

M07E.L # CANT ALLOCMEM, Dl ;PUT ERROR CODE IN Dl 

ENDE_MAKEAWINDOW 

ZERO D0 ; CLEAR D0, INDICATE ERROR I 
RTS 

ERR_MAKEAWINDOW 

MOVEQ.L #CANTOPENWINDOW,Dl ;PUT ERROR CODE IN Dl 
BRA ENDE_MAKEAWINDOW 

IFD GFX fONLY ASSEMBLE IF GFX ROUTINES AND EQUATES ALSO INCLUDEDI 
CLEARWINDOWi SUBROUTINE ENTER WITH POINTER TO WINDOW STRUCTURE IN A0 
~; COLOR REG # IN D0 

ZERO D0 ;USE BACKGROUND COLOR REG t IN D0 

FILLWINDOW (ENTER HERE IF YOU HAVE YOUR COLOR REG # IN D0 

"MOVE.L WW.RPORT(A0),RP ;FIND THIS WINDOW'S RASTPORT ADDRESS 

SETAPEN RP ;SET THE -A- PEN FOR THIS RASTPORT (MACRO) 
MOVE.W WW.WIDTH(A0),D2 
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STORAGE FOR POINTER TO ALLOCATED NEWWINDOW STRUCTURE 
STORAGE FOR POINTER TO WINDOW ONCE OPENED 
CAN BE CHANGED TO CUSTOMSCREEN IF NECESSARY 
STORAGE FOR POINTER TO TITLE NULL-TERMINATED TEXT 



SUBI.W #4,D2 .-AVOID CREAMING BORDERS, DRAGBAR, ETC. 

MOVE.W WW. HEIGHT (A0),D3 

SUBI.W #2,D3 

MOVE.W #2,D0 

MOVE.W #10, Dl 

RECTFILL RP ;USE GRAPHICS LIBRARY RECTFILL ROUTINE (MACRO) 

RTS 

ENDC 

NEWWINDOW 

DC.L 
JTHISWINDOW 

DC.L 
_THISTYPE 

DC.W WBENCHSCREEN 
_THISTITLE 

DC.L e 
_THISIDCMP 

DC . L CLOSEWINDOWl MENUPICK 1 MOUSEBUTTONS I NEWSIZE 1 GADGETUP I GADGETDOWN 
_THISFLAGS 

~DC . L ACTIVATE 1 WINDOWSIZING 1 WINDOWDRAG 1 WINDOWDEPTH 1 WINDOWCLOSE 1 SMART REFRESH 
_THISCREEN 

DC.L ; STORAGE FOR POINTER TO CUSTOM SCREEN 

Using the MAKEAWINDOW Subroutine 

MAKEAWINDOW has its own standard variables to simplify 
the creation and filling of a NEWWINDOW structure. The 
MAKEAWINDOW subroutine will do most of the work. 

MAKEAWINDOW allocates a NEWWINDOW structure, 
fills it with typical default window parameters, calls the library 
function OPENWINDOW, and deallocates the NEWWINDOW 
structure. Most programs in this book use MAKEAWINDOW 
to simplify programming windows. The code listing for 
MAKEAWINDOW is heavily commented. 

Using MAKEAWINDOW requires very little preparation. 

• Place a pointer to the window's title in _THISTITLE (a vari- 
able declared in the MAKEAWINDOW code). 

• Specify the left, top, width, and height values in registers D4, 
D5, D6, and D7, respectively. 

• Issue the instruction BSR MAKEAWINDOW. 

If there is no error, your window will open and a pointer 
to the resulting WINDOW structure will be placed in register 
DO. If there is an error, DO will contain a 0. 

Listing 16-4 calls MAKEAWINDOW: 

Listing 16-4. Using the MAKEAWINDOW Support Routine 



LEA 


_THISTITLE,AO 




MOVE.L 


#MYWINDOWTITLE,(A0) 


PUT POINTER TO MY 
TEXT INTO -THISTITLE 


M0VE.W 


#40,D4 


LEFTEDGE 


MOVE.W 


#15,D5 


TOPEDGE 


MOVE.W 


#300,D6 


WIDTH 
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u 


MOVE.W 


#100,D7 


HEIGHT 


u 


BSR 


MAKEAWINDOW 


CALL THE SUBROUTINE 






TO CREATE A WINDOW 




TST.L 


DO 






BEQ 


ERROR 


ERROR BRANCH IF 


u 






SUBROUTINE RETURNS 






AO 




MOVE.L 


DO.WINDOW 


OTHERWISE, SAVE 


u 






POINTER TO WINDOW 






STRUCTURE 




MYW1NDOWTITLE 




LABEL FOR WINDOW 
TITLE TEXT 




DC.B 


' THIS IS A WINDOW TITLE 


',0 WINDOW 




DC.L 




; BY MAKEAWINDOW 


STORAGE FOR THE 
POINTER RETURNED 





Note that MAKEAWINDOW has standard FLAGS and 
IDCMPFLAGS which are used almost universally in Intuition 
window programming. If you wish to have a different com- 
bination of flags, either edit the WINDOWS.ASM file or use 
code to place your own flags into the _THISFLAGS and 
_THISIDCMP variables, prior to calling MAKEAWINDOW. 
You'll find examples of this in several of the program listings. 



The MAKEWIN Macro 

In addition to the MAKEAWINDOW subroutine, the 
WINDOWS.ASM file contains a macro which itself calls 
MAKEAWINDOW. Depending on which style of programming 
is most convenient, you can substitute the macro MAKEWIN 
for a call to the MAKEAWINDOW subroutine. Listing 16-5 il- 
lustrates the use of the MAKEWIN macro. 

Listing 16-5. Examples of the MAKEWIN Macro 

USING MAKEWIN WITH 5 PARAM- 
ETERS FOR AUTOMATIC ERROR 
BRANCHING 

MAKES 300 X 80 WINDOW AT 
20,20 

AUTOMATICALLY BRANCHES TO 
ERROR_WINDOW 
LABEL IF UNSUCCESSFUL 

USING MAKEWIN WITH 4 PARAM- 
ETERS AND DOING EXPLICIT 
ERROR CHECKING 
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MAKEWIN 0,0,640,200 



TST.L 
BEQ 



DO 
ERROR 



; MAKES 640 X 200 WINDOW AT 
;0,0 

; BUT WE DO OUR OWN ERROR 
; CHECKING THIS WAY 



n 



n 
n 
n 



The CLEARWINDOW (FILLWINDOW) Subroutine 

You can use the CLEARWINDOW function to clear a window 
(set it to the background color), or the FILLWINDOW function 
to fill a window with a solid color. 

To clear a window, place the address of the window struc- 
ture in address register AO and BSR CLEARWINDOW. If you 
wish to fill with another color, place the color register number 
(1-3) into DO, put the window address in AO, and BSR 
FILLWINDOW. An example is Listing 16-6. 

Listing 16-6. A Call to FILLWINDOW Colors a Whole Window 



MOVEA.L WINDOW.A0 



MOVE.L 
BSR 



#2,D0 
FILLWINDOW 



PUT ADDRESS OF WINDOW STRUCTURE 

INTOA0 

USE COLOR #2 

FILL WINDOW WITH COLOR REGISTER #2 



WINDOW1.ASM uses a direct declaration of the 
NEWWINDOW structure. WINDOW2.ASM uses the 
MAKEAWINDOW and CLEARWINDOW/FILLWINDOW 
routines. Note the loop in which both programs scan for a 
window close message from the user. This is an example of 
using the IDCMP messages, which will be explored at greater 
depth later on. 

Before going further into the details of window varieties, 
you should take the time to experiment with the programs be- 
low (Listings 16-7 and 16-8). 

Listing 16-7. WINDOW1.ASM 

##;WINDOWl.ASM BY DANIEL WOLF 
.-COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 
;09/10/87 

BRA _START 

INCLUDE "HEADER" 

MAIN 



LEA NEWWINDOW, A0 
INTLIB OPENWINDOW 
MOVE.L D0, WINDOW 
BEQ ERROR 



;THIS MUST BE THE LABEL OF THE PROGRAM 

•PUT POINTER TO NEWWINDOW STRUCTURE INTO 
;AND OPEN THE WINDOW 

J SAVE POINTER TO THIS WINDOW STRUCTURE 
; WHOOPS, POINTER = 01 
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(*** NOW WAIT FOR IDCMP TO REPORT A CLOSEWINDOW MESSAGE *** 



LOOP 
MOVE. I. WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S LOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L #CLOSEWINDOW, D2 
BEQ.S DONE 
BRA LOOP 



• USE POINTER TO WINDOW TO FIND WINDOW'S I/O PORT 
; PLACE POINTER TO WINDOW'S PORT IN A0 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



[MESSAGE SHOULD BE AVAILABLE AFTER 'WAITPORT' 

(POINTER TO INTUIMESSAGE COMES BACK IN D0 

[NO MESSAGE FOUND THERE, SO LOOP (SHORT BRANCH) 

[POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

[CLOSEWINDOW AND MENUPICK MESSAGES APPEAR HERE 

[MENU AND MENUITEM APPEAR HERE 

[KEYS APPEAR HERE 

[QUICK, SEND MESSAGE BACK NOW1 

[COMPARE CONTENTS OF D2 WITH VALUE OF 'CLOSEWINDOW' 
[IF THEY'RE EQUAL, THIS IS A CLOSEWINDOW MESSAGEl 
[OTHERWISE, BRANCH ALWAYS (BRA) BACK TO LOOP 



u 
u 

u 
u 
u 



[*** NOW FINISH UP, CLOSE WINDOW, AND EXIT TO SKELETON 



DONE 

ZERO D0 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S QUIT 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
QUIT 

PULLREG D0 

RTS 

ERROR 
MOVEQ #CANTOPENWINDOW, D0 
RTS 

[*** DATA STORAGE *** 

MYWINDOWTITLE 



[NO ERRORS, SO PLACE IN D0 AS ERROR CODE 

[HIDE D0 FOR A MOMENT ON THE STACK 

[CHECK FOR AN OPEN WINDOW 

[IF 'WINDOW' = , THEN NO WINDOW WAS OPENED 

[THERE IS A WINDOW 

[SO CLOSE IT 

[RESTORE D0 NOW 

[RETURN TO 'CLEANUP' PORTION OF SKELETON 



[PUT ERROR CODE #21, "CAN'T OPEN WINDOW" 
[EXIT TO SKELETON NOW1 



[NULL-TERMINATED WINDOW TITLE TEXT 



DC.B ' WINDOW1 BY D.WOLF ',0 



EVENPC 



WINDOW DC.L 
RP DC.L 



[WORD-ALIGN MEMORY AFTER DC.B I 



[STORAGE FOR POINTER TO THE WINDOW STRUCTURE 
[STORAGE FOR WINDOW'S 'RASTPORT' POINTER 



,-LEFTEDGE 

[TOPEDGE 

(WIDTH 

[HEIGHT 

[DETAILPEN (= FF, MAXIMUM REGARDLESS OF SCREEN DEPTH1) 

[BLOCKPEN 



NEWWINDOW 
DC.W 40 
DC.W 15 
DC.W 300 
DC.W 160 
DC.B -1 
DC.B -1 
DC.L CLOSEWINDOW 

DC . L ACTIVATE I WINDOWSIZING I WINDOWDRAG 1 WINDOWDEPTH I WINDOWCLOSE 1 SMART_REFRESH 
DC.L (POINTER TO FIRST USER-DEFINED GADGET 

DC.L [POINTER TO USER-DEFINED CHECKMARK 

DC.L MYWINDOWTITLE [POINTER TO TITLE TEXT 
DC.L (POINTER TO CUSTOM SCREEN 

(POINTER TO CUSTOM BITMAP 

(MINWIDTH 

(MINHEIGHT 

(MAXWIDTH 

[ MAXHEIGHT 

[TYPE OF SCREEN THIS WINDOW IS IN 



DC.L 

DC.W 50 

DC.W 20 

DC.W 640 

DC.W 400 

DC.W WBENCHSCREEN 



END 
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Listing 16-8. WIND0W2.ASM 

##[WIND0W2.ASM BY DANIEL WOLF 
[COPYRIGHT 1987 BY COMPUTE I PUBLICATIONS 
; 09/10/87 

BRA _START 
WIN EQU 1 ;SET DEFINITION OF SYMBOL TO BE USED BY THE HEADER 

INCLUDE "HEADER" ; BRING IN THE 'WINDOWS' ROUTINES 

MAIN [THIS MUST BE THE LABEL OF THE PROGRAM 

;NOW USE 'MAKEAWIN' MACRO FOR SEVERAL 

MAKEWIN #MYWINDOWTITLE, 40, 15, 300, 160, ERROR 

MOVE.L D0, WINDOW ;SAVE POINTER TO THIS WINDOW STRUCTURE 

LEA _THISFLAGS,A0 

MOVE.L #WINDOWDRAG,(A0) [NO CLOSEWIHDOW GADGET IN THESE WINDOWS 
;NO AMBIGUITY WHICH TO CLOSE TO END PROGRAM 

MAKEWIN #MYWINDOWTITLE, 50 , 30 , 200 , 100, ERROR 

MOVE.L D0,WIN2 

MAKEWIN #MYWINDOWTITLE , 60 , 40 , 1 50 , 80 , ERROR 

MOVE.L D0.WIN3 

MAKEWIN #MYWINDOWTITLE, 70 , 50 , 100 , 70 , ERROR 

MOVE.L D0.WIN4 

.*** N0W WAIT F0R IDCMP T0 report A CLOSEWINDOW MESSAGE *** 
; ON LARGEST WINDOW ONLY I 1 I 



LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BF.Q.S LOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L #CLOSEWINDOW, D2 
BEQ.S DONE 
BRA LOOP 



•USE POINTER TO WINDOW TO FIND WINDOW'S I/O PORT 
! PLACE POINTER TO WINDOW'S PORT IN A0 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



; MESSAGE SHOULD BE AVAILABLE AFTER 'WAITPORT' 

.•POINTER TO INTUIMESSAGE COMES BACK IN D0 

;NO MESSAGE FOUND THERE, SO LOOP (SHORT BRANCH) 

[POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

[CLOSEWINDOW AND MENUPIC MESSAGES APPEAR HERE 

[MENU AND MENUITEM APPEAR HERE 

[KEYS APPEAR HERE 

[QUICK, SEND MESSAGE BACK NOW1 

[COMPARE CONTENTS OF D2 WITH VALUE OF 'CLOSEWINDOW' 
[IF THEY'RE EQUAL, THIS IS A CLOSEWINDOW MESSAGE1 
[OTHERWISE, BRANCH ALWAYS (BRA) BACK TO LOOP 



NOW FINISH UP, CLOSE WINDOWS, AND EXIT TO STARTUP *** 



DONE 
ZERO D0 
PUSHREG D0 
MOVE.L WINDOW, D0 
BEQ.S QUIT 
MOVE.L D0.A0 
INTLIB CLOSEWINDOW 
MOVE.L WIN2.D0 
BEQ.S QUIT 
MOVE.L D0.A0 
INTLIB CLOSEWINDOW 
MOVE.L WIN3.D0 
BEQ.S QUIT 
MOVE.L D0.A0 
INTLIB CLOSEWINDOW 
MOVE.L WIN4.D0 
BEQ.S QUIT 
MOVE.L D0.A0 
INTLIB CLOSEWINDOW 

QUIT 
PULLREG D0 

RTS 



[NO ERRORS, SO PLACE IN D0 AS ERROR CODE 

[HIDE D0 FOR A MOMENT ON THE STACK 

[CHECK FOR AN OPEN WINDOW 

[IF 'WINDOW' = , THEN NO WINDOW WAS OPENED 

[THERE IS A WINDOW 

[SO CLOSE IT 



[RESTORE D0 NOW 

[RETURN TO 'CLEANUP' PORTION OF STARTUP 
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ERROR 

MOVEQ #CANTOPENWINDOW,D0 ;PUT ERROR CODE #21, "CAN'T OPEN WINDOW" 

RTS ;EXIT TO STARTUP NOWI 

-*** DATA STORAGE *** 

MYWINDOWTITLE ; NULL-TERMINATED WINDOW TITLE TEXT 

DC.B ' Window2 BY D.WOLF ',0 

EVENPC I WORD-ALIGN MEMORY AFTER DC.B I 



WINDOW DC.L 8 
WIN2 DC.L 
WIN3 DC.L 
WIN4 DC.L 

END 



.•STORAGE FOR POINTER TO THE WINDOW STRUCTURE 



The WINDOW Structure 

Until now, our discussion has centered around the 
NEWWINDOW structure and its use with OPENWINDOW. 
Now, you're ready to look at the WINDOW structure table and 
its fields. 

Here is an overview of the information in the WINDOW 
structure created by OPENWINDOW. A program can look up 
the values in the WINDOW fields as needed. By placing the 
address of the window structure in an address register, its 
fields can be accessed by means of offsets. 

Table 16-4. The Intuition WINDOW Structure 



Symbol: WW 






Size: 128 bytes ($80 bytes) 






Field 






Size Name 


Offset 


Description 


Long WW.NEXT 


$0 


Pointer to next window 


Word WW.LEFTEDGE 


4 


Number of pixels from the 
left edge of screen 


Word WW.TOPEDGE 


6 


Number of pixels from top 
edge of screen 


Word WW.WIDTH 


8 


Number of pixels wide 


Word WW.HEIGHT 


10 


Number of pixels high 


Word WW.MOUSEX 


12 


Mouse X coordinate 


Word WW.MOUSEY 


14 


Mouse Y coordinate 


Word WW.MINWIDTH 


16 


Number of pixels minimum 
width 


Word WW.MINHEIGHT 


18 


Number of pixels minimum 

height 


Word WW.MAXWIDTH 


20 


Number of pixels maximum 
width 


Word WW.MAXHEIGHT 


22 


Number of pixels maximum 
height 



u 
Li 
u 
u 
u 



188 



u 

u 

u 
u 
u 



n 




Amiga Machine Language Programming 


n 










n 


Field 

Size 


Name 


Offset 


Description 




Long 


WW.FLAGS 


24 


Window flag bits 


n 


Long 


WW.MENU 


28 


Pointer to menu structure 


Long 


WW.TITLE 


32 


Pointer to window title 




Long 


WW.FIRSTREQUEST 


36 


Pointer to first requester 


n 


Long 


WW.DMREQUEST 


40 


Pointer to double-click 








requester 




Word 


WW.REQCOUNT 


44 


Number of requesters block- 
ing action 




Long 


WW.WSCREEN 


46 


Pointer to this window's 
screen 




Long 


WW.RPORT 


50 


Pointer to this window's 
rastport 




Byte 


WW.BORDERLEFT 


54 


Number of pixels left border 
thickness 




Byte 


WW.BORDERTOP 


55 


Number of pixels top border 
thickness 




Byte 


WW.BORDERRIGHT 


56 


Number of pixels right border 
thickness 




Byte 


WW.BORDERBOTTOM 


57 


Number of pixels bottom bor- 
der thickness 




Long 


WW.BORDERRPORT 


58 


Pointer to rastport for border 




Long 


WW.FIRSTGADGET 


62 


Pointer to first gadget in 
window 




Long 


WW.FARENT 


66 


Used by system for 
open/close 




Long 


WW.DESCENDANT 


70 


Used by system for 
open/close 




Long 


WW.POINTER 


74 


Pointer to the mouse pointer 
sprite data 




Byte 


WW.PTRHEIGHT 


78 


Mouse pointer sprite height 


n 


Byte 


WW.PTRWIDTH 


79 


Mouse pointer sprite width 
(<=16) 


i 


Byte 


WW.XOFFSET 


80 


Mouse pointer sprite x offset 




Byte 


WW.YOFFSET 


81 


Mouse pointer sprite y offset 


n 


Long 


WW.IDCMPFLAGS 


82 


The IDCMPFLAGS for this 
window 




Long 


WW.USERPORT 


86 


Pointer to message port 


r-*i 


Long 


WW.WINDOWPORT 


90 


Pointer to message port 


n 


Long 


WW.MESSAGEKEY 


94 


Pointer to INTUIMESSAGE 


^v^ta 


Byte 


WW.DETAILPEN 


98 


Drawing pen for borders and 
so on 


n 


Byte 


WW.BLOCKPEN 


99 


Drawing pen for menu, 
dragbar, and so on 
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Field 








Size 


Name 


Offset 


Description 


Long 


WW.CHECKMARK 


100 


Pointer to checkmark image 


Long 


WW.SCREENTITLE 


104 


Pointer screen title (if not 0, 
screen title when window is 

active) 


Word 


WW.GZZMOUSEX 


108 


Mouse x position if 

GIMMEZEROZERO-type 

window 


Word 


WW.GZZMOUSEY 


110 


Mouse y position if 

GIMMEZEROZERO-type 

window 


Word 


WW.GZZWIDTH 


112 


Width if GIMMEZEROZERO- 
type window 


Word 


WW.GZZHEIGHT 


114 


Height if 

GIMMEZEROZERO-type 

window 


Long 


WW.EXTDATA 


116 


Pointer to external data 


Long 


WW.USERDATA 


120 


Pointer to user data 


Long 


WW.WLAYER 


124 


Duplicates rastport layer 
pointer 



u 
u 
u 
u 
u 



Refreshing Windows 

Refresh is a procedure that redraws a window and its contents 
on the screen after it has been covered or damaged. Although 
the Amiga's operating system makes the screen look as if it 
were multidimensional, with menus, windows, and other dis- 
plays covering and uncovering each other, the fact is, there is 
only one dimension. If a menu is pulled down over a window, 
or another window appears "in front of" an existing window, 
damage is done. In order to maintain the illusion of a three di- 
mensional screen, the damage must be repaired as quickly as 
it is sustained. 

SIMPLE—REFRESH provides a strategy to conserve chip 
memory. SIMPLE—REFRESH means your program is responsi- 
ble for refreshing when damage has been done. Use it when 
it's unlikely that a window will be covered and later uncov- 
ered. If the window will never be damaged, it doesn't need to 
be refreshed. 
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SMART—REFRESH makes the system set aside chip mem- 
ory for any rectangular region of a window that is covered up. 
When the intruding window or menu is gone, a SMART- 
REFRESH window automatically redisplays the damaged sec- 
tion. Your program doesn't have to do anything at all. The rec- 
tangles saved are called clipping rectangles. Each clipping 
rectangle must be stored in chip memory. 

SUPER—BITMAP refreshing sets aside bitmap memory 
(once again, in chip memory) for remembering the window's 
entire contents. The bitmap memory may be larger in area 
than the window itself. Although SUPER-BITMAP is very 
memory-hungry, it permits your window to be scrolled over a 
larger area, like looking at a page through a small rectangle 
cut out of a piece of cardboard. 

In all, there are dozens of ways to present and use win- 
dows in Intuition programs. This book is intended to get you 
started using them, but it would take another book as large as 
this one to fully cover windows. When you've achieved a level 
of mastery over the use of windows described in this text, you 
should review the Amiga Intuition Reference Manual section on 
windows to move on to the more exotic window forms. 
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The IDCMP Flags 

This section of Chapter 17 is both a review and a closer look [^_J 

at the powerful control exercised by this particular NEW- 
WINDOW slot. 

NEWWINDOW Structure ICDMPFLAGS Field 

Once again, the IDCMPFLAGS field in the NEWWINDOW 
structure provides the potential for dozens of combinations of 
features. The bits in this field control the flow of events to 
your program, via Intuitions's communications channel to 
your window. You can choose to receive messages about a 
wide variety of user actions, such as mouse button events, 
menu use, gadget clicks, and so on. You can also use these 
flags to make sure certain circumstances prevail before a user 
is allowed to complete some action. For example, you can set 
the SIZEVERIFY flag to assure that window sizing by the user 
takes place only when your window is not being drawn by 
code that requires the window size to remain constant. 

Table 17-1 provides a review of the IDCMPFLAGS, hex 
values, and brief descriptions. For additional information, see 
how they're used in the program examples, and review the 
OPENWINDOW function description in the Amiga Intuition 
Reference Manual. 



U 
U 



Table 17-1. Intuition Window IDCMPFLAGS 

Name Bit Value Description 

SIZEVERIFY 0001 Report sizing request 

NEWSIZE 0002 Report user changed window size 

REFRESHWINDOW 0004 Report window needs refreshing 

MOUSEBUTTONS 0008 Report non-Intuition mouse but- 
ton use I , 

MOUSEMOVE 0010 Report all mouse movements ! ! 

GADGETDOWN 0020 Report left mouse button down on 

g ad g et , , 

GADGETUP 0040 Report left mouse button up on I 

gadget u ~ i 
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Name 


Bit Value 


Description 


REQSET 


0080 


Report first requester in window 


MENUPICK 


0100 


Report menu selection made 


CLOSEWINDOW 


0200 


Report user clicked windowclose 
gadget 


RAWKEY 


0400 


Report all raw key codes 


REQVERIFY 


0800 


Report attempt to open requester 


REQCLEAR 


1000 


Report final requester removed 


MENUVERIFY 


2000 


Report attempt to use menu 


DISKINSERTED 


8000 


Report user inserted a disk 


DISKREMOVED 


10000 


Report user removed a disk 


ACTIVEWINDOW 


40000 


Report when window is activated 


INACTIVEWINDOW 


80000 


Report when window is 
deactivated 


DELTAMOVE 


100000 


Report relative mouse movements 


VANILLAKEY 


200000 


Report ASCII keycodes 


INTUITICKS 


400000 


Report timer events every tenth of 
a second 



Here are some things to bear in mind when using these 
flag bits to control the receipt of event messages by your pro- 
gram. The more bits you set, the more messages will arrive. Be 
sure that you need the incoming information, because commu- 
nication requires memory and system time overhead. It also 
requires your programs SYSLIB GETMSG and SYSLIB 
REPLYMSG, frequently, to process the messages. 

If you set the VERIFY bit, your program should get and 
reply to those messages quickly and, thereby, permit the re- 
quester, menu, or sizing operations to take place. These flags 
are for your convenience to prevent graphics disruption in 
your window, but don't let them tie up your program's progress 
or the user's apparent ability to interact with the window. 

Review the WINDOW1 and WINDOW2 programs in the 
previous chapter to see how they receive and reply to mes- 
sages. Listing 17-1 is a typical program fragment that monitors 
the IDCMP messages. It begins with the label LOOP for a rea- 
son. This segment of program code is repeatedly executed to 
determine if an IDCMP message has occurred. If an appropri- 
ate message has arrived (namely one specified by the IDCMP 
flags used with that window), this code will see it and the pro- 
gram can respond accordingly. 
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Waiting for a Message 

In the Amiga's multitasking environment, it's important to 
suspend the program's usual operations while awaiting the 
user's next message. This is accomplished using the EXEC 
WAITPORT library routine. 

WAITPORT tells the program to wait until a message ar- 
rives at the IDCMP Port. WAITPORT needs to know on which 
port to wait. Put the address of the WINDOW STRUCTURE'S 
IDCMP PORT in register AO, prior to calling WAITPORT. 
That makes the WAITPORT function look at the IDCMP for 
that window. 

Waiting for messages could be accomplished by a loop of 
MC68000 instructions that repeatedly scan until a message is 
detected, but that would be wasteful of the Amiga's resources; 
using WAITPORT is much better. WAITPORT lets other tasks 
and processes run while the current program is suspended and 
awaiting a response. WAITPORT relieves the MC68000 micro- 
processor of continuously monitoring for a message. 

In the round-robin operation of all Amiga tasks, the wait- 
ing program only uses a small portion of the time allotted to it 
when its turn comes around. If no messages have yet arrived, 
it quickly relinquishes its turn and allows other tasks to 
continue. 

Listing 17-1. WAITPORT Loop for IDCMP CLOSEWINDOW 
Messages 



LOOP 



u 
u 
u 
u 
u 
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MOVE.L 


WINDOW.AO 


PUT ADDRESS OF WINDOW 
INTOAO 




MOVE.L 


WW.USERPORT(A0),A0 


LOOK UP IDCMP'S ADDRESS 








FOR THIS WINDOW 


u 


SYSLIB 


WAITPORT 


JUST WAIT TILL SOME MES- 






SAGE ARRIVES 


MOVE.L 


WINDOW.A0 


PUT ADDRESS OF WINDOW 








INTO AO 


u 


MOVE.L 


WW.USERPORT(A0),A0 


GET IDCMP ADDRESS OF THIS 






WINDOW AGAIN 




SYSLIB 


GETMSG 


MACRO GETMSG CALL FOR 


u 






ADDRESS OF MESSAGE 


TST.L 


DO 


WAS THERE REALLY NO 








MESSAGE? 


u 


BEQ.S 


LOOP 


NO MESSAGE, JUST GO BACK 






AND WAITPORT AGAIN 


u 
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MOVE.L D0,A1 

MOVE.L IM.CLASS(A1),D2 

MOVE.W IM.C0DE(A1),D3 

MOVE.W IM.QUALIFIER(A1),D4 

SYSLIB REPLYMSG 

CMP.L #CL0SEWIND0W,D2 

BEQ.S DONE 

BRA LOOP 



MESSAGE ARRIVED, ADDRESS 

INT0A1 

CLOSEWINDOW, GADGET, and 

MENU SELECT etc. 

MENU SELECTION NUMBERS 

APPEAR HERE 

KEYBOARD INFORMATION 

APPEARS HERE 

MACRO CALL TO RETURN THE 

MESSAGE 

DID THE CLOSEWINDOW MES- 
SAGE ARRIVE? 

IF SO, BRANCH TO (PERHAPS) 
PROGRAM END 

WE WERE ONLY LOOKING FOR 
CLOSEWINDOW, 

WHICH WASN'T THE MESSAGE, 
SO WAITPORT AGAIN 



Exec library functions fetch a message and return it after 
it's processed in this loop. WAITPORT lets the program know 
that a message has arrived. Other Exec functions are used to 
handle the message. They are GETMSG and REPLYMSG. 
Messages are sent by the operating system to the IDCMP and 
consist of information regarding various input events specified 
in the IDCMP flags. 

When a GETMSG call returns a message, an address is 
the result. The address is placed in register DO. It points to 
a location in an INTUIMESSAGE structure. Within the 
INTUIMESSAGE structure are the IDCMPCLASS and 
IDCMPCODE fields (long-word and word values, respec- 
tively). Once these fields have been examined by the program 
(and copied to registers or memory as necessary), you can 
SYSLIB REPLYMSG to unload the message back to its source. 
The IDCMPCLASS and IDCMPCODE fields contain a value 
that reflects which of the many possible messages was re- 
ceived. If the CLOSEWINDOW message was sent because the 
user clicked a closewindow gadget, the ICDMPCLASS field 
will be equal to CLOSEWINDOW. 

If you wish, you can arrange for your window to receive a 
blizzard of event messages from the user and the system. Use 
the WINDOW1 and WINDOW2 programs to experiment with 
combinations of settings of the IDCMP flags in the NEW- 
WINDOW structure. 
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Once the window is opened (by using the MAKE- i | 

AWINDOW routine or other code), you may change the ^- ~* 

IDCMPFLAGS during the operation of your program by se- 
lecting the combination of flags you desire, and by using the I j 
MODIFYIDCMP function (using register DO to pass the value ^~~ 
for flags and register AO to pass the address of the WINDOW 
structure): 



Listing 17-2. Specifying a New IDCMP FLAGS Combination in an 
Existing WINDOW 

; CHOOSE SOME 
FLAGS 
SPECIFY THE 



MOVE.L #(DESIRED COMBINATION OF IDCMP FLAGS),D0 
MOVEA.L WINDOW.A0 
INTLIB MODIFYIDCMP 



WINDOW 
MACRO CALL TO 
FUNCTION 



u 



The best ways to learn about the variety of effects that 
can be achieved with FLAGS and IDCMPFLAGS, is to try 
your own combinations, study the example listings, and refer 
to the Amiga Intuition Reference Manual. 

INTUITEXT: Intuition Text Handling 

There are two ways to get text onto the screen within a win- 
dow on the Amiga: 

• If a program is running from the CLI, it already has an IN- 
PUT file and OUTPUT file assigned by STARTUP ASM, and 
you use AmigaDOS WRITE and READ calls to handle text 
directly in the CLI window. 

• When the program has its own Intuition window open (per- 
haps the program started up from the Workbench), use the I J 
Intuition PRINTITEXT routine to output text. '*--' 

Intuition window also requires IDCMP messages to read , -, 

characters (IDCMP INTUIMESSAGE CODE field) from the ^J 

keyboard. You can get the keystroke codes in RAW form or 
VANILLAKEY (ASCII code) form this way. 

It is also possible to use AmigaDOS to open a separate [^J 

CLI-like window for input and output. You'll recall that this 
was called a CONsole device. It represents a powerful way to ■ — 

use AmigaDOS library routines in a program that is also using jl 
Intuition windows. AmigaDOS text I/O was covered in the 
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earlier chapter on AmigaDOS, so we'll concentrate here on the 
Intuition text concepts including INTUITEXT and the variety 
of ways INTUITEXT structures are used with other Intuition 
structures (Menus, Menultems, Gadgets, and so on). 



p- Intuition Window Text Output: INTUITEXT 

! | STRUCTURE, PRINTITEXT3 

Intuition can place any null-terminated text anywhere in any 
open Intuition window, using any system font, style, or color. 
It uses graphics routines, internally, to draw the text into your 
window. A program must first transform simple ASCII text 
(declared using DC.B directives — see examples) into an 
INTUITEXT structure before Intuition can use it. 

The INTUITEXT structure is a 20-byte structure that pro- 
vides the data Intuition needs to render text graphically in a 
window. 

See the INTUITEXT STRUCTURE table in Table 17-2. 
One of the fields of an INTUITEXT structure is a pointer to 
your text. Other fields specify the foreground and background 
colors for the text, drawing mode (JAM1, JAM2, or COMPLE- 
MENT), pixel positions for the start of the text, font, and a 
pointer to the next INTUITEXT structure. You can leave a 
value of in the FONT field. You can also leave a value in 
the NEXT pointer. If the NEXT pointer is set to another 
INTUITEXT structure's address, a call to PRINTITEXT will 
print it as well. If the FONT pointer is set to 0, the default sys- 
tem font is used (TOPAZ8 or TOPAZ9 — depending on whether 
you selected 60 or 80 characters on your preferences menu). If 
your code opens the Diskfont library, you can (by studying the 
Amiga Intuition Reference Manual) use the other fonts. For sim- 
plicity, these programs use subroutines that are preset to use 
the default system font. 

Table 17-2. Intuition INTUITEXT Structure 

Symbol: IT 

Size: 22 bytes ($16 bytes) 

Field Size Name Offset Description 

Byte IT.FRONTPEN Color register number for 

foreground 
Byte IT.BACKPEN 2 Color register number for 

background 
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Field Size 


Name Offset 


Description 


u 


Byte 


IT.DRAWMODE 4 


JAM1, JAM2, OR XOR 




Word 


IT.LEFTEDGE 6 


Number of pixels from the 


u 






left edge 


Word 


IT.TOPEDGE 8 


Number of pixels from the 








top edge 


1 " 1 


Long 


IT.ITEXTFONT 10 


Pointer to a font or for de- 


u 






fault font 


Long 


IT.ITEXT 14 


Pointer to a null-terminated 
text string 




Long 


IT.NEXTTEXT 18 


Pointer to next INTUITEXT 
structure 





For easier access to the Intuition text-handling routines 
and structures, this chapter has a listing to be added to the in- 
clude files you've typed in during previous sections. This file is 
called TEXTS. ASM and consists of subroutines and macros for 
easily using Intuition text. Listing 17-3 has the code for 
TEXTS.ASM, which can be typed in using the EMACS editor. 
Following the conventions developed in Chapter 3, we refer to 
the disk to which you've been depositing the type-in files as 
the DEV disk. Using EMACS or the editor of your choice, type 
in TEXTS.ASM from Listing 17-3 and save it to the DEV disk 
with the name: 

DEV:RAMIT/INCLUDES/TEXTS.ASM 



Listing 17-3. TEXTS.ASM 

Intuition Text Handling Support Routines and Macros 

.*************#****************** TEXTS.ASM BY DANIEL WOLF 

.-COPYRIGHT 1987 BY COMPUTE! BOOKS 

;03/21/87 

;TEXT SUPPORT ROUTINES 

;MAKE AND PRINT NEW ITEXT AND GET ADDRESS OF NEW ITEXT STRUCTURE BACK IN D0 



PRINTNEWAT MACRO 
MOVE.L \1,A0 
LEA \2,A1 
MOVE.W #\3,D0 
MOVE.W #\4,D1 
BSR _PRINTTEXT 
TST.L D0 
BEQ \S 
ENDM 



; PRINT EXISTING INTUITEXT STRUCTURE 



; WINDOW, TEXT, LEFT, TOP, ERROR 

; POINTER TO EXISTING WINDOW 

; POINTER TO FRESH NULL-TERMINATED TEXT 

;LEFT 

;TOP 

;MAKE NEW ITEXT (IN D0 IF SUCCESSFUL) AND PRINT! 



PRINTOLDAT MACRO 
MOVE.L \1,A0 
MOVE.L \2,A1 
MOVE.W #\3,D0 
MOVE.W #\4,D1 
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; POINTER TO EXISTING WINDOW 

;PUT ADDRESS OF EXISTING INTUITEXT INTO Al 

,-LEFT 

rTOP 
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BSR _PRINTTXT (JUST PRINT EXISTING INTUITEXT 
TST.L D0 
BEQ \5 
ENDM 

;JUST MAKE AN INTUITEXT, RETURN ADDRESS IN D0 



MAKEITEX MACRO 
LEA \1,A0 
BSR MAKEATEXT 
TST.L D0 
BEQ \2 

MOVE.L D0,\3 
ENDM 

MAKEATEXT 

PUSHREG A0 

REMEMBERPUBMEM 

MOVE.L D0,A0 

PULLREG Al 

PUSHREG A0 

BSR CREATETEXT 

PULLREG D0 

RTS 
ERR MITEXT 

PULLREG A0 

RTS 



;TEXT, ERROR, RESULTPTR 
;LOAD ADDRESS OF N.T. TEXT (\1 PARAMETER) 



;IF ERROR, BRANCH TO \2 PARAMETER 
-STORE ADDRESS AT \3 PARAMETER 

; RETURNS ADDRESS IF SUCCESSFUL IN D0 

(SUBROUTINE - ENTER WITH PTR TO N.T. TEXT IN A0 
;PUSH ADDRESS OF N.T. TEXT 
REMEMBERKEY, #SIZE . IT, ERR_MITEXT 

•GET PTR TO N.T. TEXT FROM STACK 
;SAVE PTR TO ITEXT MEM BLOCK ON STACK 
;FILL IN THE INTUITEXT STRUCTURE 

; RETURN WITH ADDRESS OF ITEXT IN D0 

(RETURN WITH IN D0 IF ERROR ALLOCATING 



CREATETEXT; SUBROUTINE ENTER WITH POINTER TO INTUITEXT SIZED MEM BLOCK IN A0 
; POINTER TO NULL-TERMINATED TEXT IN Al 

; THIS ROUTINE FILLS THE INTUITEXT STRUCTURE WITH REASONABLE STUFF 

, IT PUTS THE TEXT 2 DOWN AND 2 OVER (PIXELS) FROM UPPER LEFT 

; AND USES PEN #2 FOR FOREGROUND 



MOVE.B #2,IT.FRONTPEN(A0) 
MOVE.B #JAM1,IT.DRAWMODE(A0) 
MOVE.W #2,IT.LEFTEDGE(A0) 
MOVE.W #2,IT.TOPEDGE(A0) 
MOVE.L A1,IT.TEXT(A0) 
RTS 



;SET FOREGROUND PEN #=2 

;DRAW TEXT IN JAM1 MODE 

; START TEXT 2 PIXELS IN FROM LEFT 

;START TEXT 2 PIXEL DOWN FROM TOP 

(POINTER TO NULL TERMINATED TEXT 



PRINTTEXT 



SUBROUTINE 



PUSHREG D0-D1/A0 

PUSHREG Al 

REMEMBERPUBMEM REMEMBERKEY, 

TST.L D0 

BEQ.S ERR_TEXT 

MOVE.L D0.A0 

PULLREG Al 

BSR CREATETEXT 

MOVE.L A0.A1 

MOVE.L A1,_THISITEXT 

PULLREG D0-D1/A0 

_PRINTTXT 
MOVE.L WW.RPORT(A0),A0 
INTLIB PRINTITEXT 
MOVE.L _THISITEXT,D0 
RTS 

ERR_TEXT 
PULLREG Al 
PULLREG D0-D1/A0 
ZERO D0 
RTS 



ENTER WITH POINTER TO WINDOW ■ IN A0 

N.T. TEXT IN Al 
LEFTEDGE IN D0 
TOPEDGE . IN Dl 

(SAVE THE REGISTERS FIRST 

♦SIZE. IT (ALLOCATE MEMORY FOR AN INTUITEXT 



(USE ADDRESS OF INTUITEXT STRUCTURE 

(NOW FILL THE INTUITEXT 

[CREATES 2-DOWN AND 2-RIGHT POSITION OFFSET 

(PUT POINTER TO INTUITEXT INTO Al 

[AND SAVE IT SO IT CAN BE RETRIEVED 

[WINDOW, LEFT, TOP OFFSETS (ADDED TO ITEXT) 

(ENTER HERE IF Al IS PTR TO ITEXT, A0 TO WINDOW 

[AND PRINT IT 

[NO ERROR, D0 • ADDRESS OF NEW INTUITEXT 



[PUT ERROR = CODE INTO D0 



JTHISITEXT 
DC.L 



[STORAGE FOR POINTER TO AN ALLOCATED INTUITEXT 
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The CREATETEXT subroutine. This routine, in the j 

TEXTS.ASM file, is called with the address of a 20-byte block ^ 
of memory for an INTUITEXT structure in register AO and the 

address of the null-terminated text in Al. CREATETEXT fills j | 

out the INTUITEXT structure with some standard default val- 
ues. The INTUITEXT structure's memory is declared (by a line 

similar to MYINTUITEXT DS.B 20) in the program code, or j I 

allocated by a call to ALLOCREMEMBER or ALLOCMEM. W 

The examples of INTUITEXT usage in upcoming chapters 
make extensive use of allocation followed by a call to 
CREATETEXT. 

The -PRINTTEXT and -PRINTTXT subroutines. This 
routine in the TEXTS.ASM file allocates and fills an 
INTUITEXT structure. All the calling program must supply is 
the x,y position of the text to be printed and a pointer to the 
null-terminated text. Register DO is used for x, Dl for y, regis- 
ter AO for the window structure pointer, and Al for the text 
pointer. 

Note that if you print the same text more than once, you 
shouldn't use the —PRINTTEXT subroutine repeatedly, be- 
cause it allocates memory. —PRINTTEXT returns the address 
of an allocated INTUITEXT in a variable labeled -THISITEXT. 
This address can be saved and used later to call —PRINTTXT. 
The first time some text is printed to a window, use 
—PRINTTEXT and save the address returned. The second and 
subsequent times, call —PRINTTXT (which skips the alloca- 
tion) using the known address of the INTUITEXT in question. 
This method is demonstrated in WINDOWPRINTASM. 

The PRINTNEWAT and PRINTOLDAT macros. These 
two macros represent the simplest way to accomplish simple 
printing of text in an Intuition window. The PRINTNEWAT j j 

macro accepts the label of a null-terminated text declaration as ^—^ 
its parameter. It calls the CREATETEXT subroutine to create a 
new INTUITEXT structure and calls _PRINTITEXT. The x and 
y positions in the window to which the text is printed are the 
other parameters for this macro. PRINTNEWAT should only be 
used to print a particular text the first time it is needed. 

PRINTOLDAT accepts the address of an existing 
INTUITEXT structure (and x and y position values) as a pa- 
rameter, and calls -PRINTTXT to print it to the window. This I ~j 
macro is used whenever an INTUITEXT structure already ex- ' — 
ists for the text you wish to display. It doesn't create a new 
structure, but rather recycles an existing one. i j 
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Listing 17-4. WINDOWPRINT Program 

Demonstration of INTUITEXT structure and TEXTS.ASM use. 

##,- WINDOWPRINT. ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 

; 09/ 10/87 

BRA _START 
TXT EQU 1 

INCLUDE "HEADER" 

MAIN ;THIS MUST BE THE LABEL OP THE PROGRAM 

LEA NEWWINDOW.A0 J PUT POINTER TO NEWWINDOW STRUCTURE INTO A0 

INTLIB OPENWINDOW ;AND OPEN THE WINDOW 

MOVE.L D0, WINDOW ;SAVE POINTER TO THIS WINDOW STRUCTURE 

BEQ ERROR ;WHOOPS, POINTER = 01 

;*** NOW PRINT SOME TEXT TO THE WINDOW WITH _PRINTTEXT SUBROUTINE *** 

MOVE.L D0,A0 ;PUT POINTER TO WINDOW INTO A0 

LEA MESSAGE, Al ; POINTER TO TEXT INTO Al 

MOVE.W #10, D0 

MOVE.W #15, Dl 

BSR _PRINTTEXT ;USE SUBROUTINE TO PRINT TEXT TO WINDOW 

TST.L D0 

BEQ ERR_DONE 

MOVE.L D0,MSG ;SAVE POINTER TO INTUITEXT WHICH CAME BACK1 

;*** NOW PRINT MORE TEXT TO WINDOW WITH PRINTNEWAT MACRO *** 

PRINTNEWAT WINDOW, MESSAGE1, 10, 30, ERROR ;MACRO EQUIVALENT TO PREVIOUS 5 LINES! 
MOVE.L D0.MSG1 ;ALSO RETURNS INTUITEXT PTR, CALLS _PRINTTEXT 

;*** NOW PRINT BOTH 'OLD' MESSAGES USING EXISTING INTUITEXTS *** 

PRINTOLDAT WINDOW, MSG, 10 , 45 , ERR_DONE 
PRINTOLDAT WINDOW, MSG1 , 10 , 60 , ERR_DONE 

.♦** N0W WAIT F0R iDCMP TO REPORT A CLOSEWINDOW MESSAGE *** 

LOOP 

MOVE.L WINDOW, A0 ;USE POINTER TO WINDOW TO FIND WINDOW'S I/O PORT 

MOVE.L WW.USERPORT(A0) ,A0 ; PLACE POINTER TO WINDOW'S PORT IN A0 

SYSLIB WAITPORT fWAIT FOR A SPECIFIED MESSAGE TO ARRIVE 
MOVE.L WINDOW.A0 
MOVE.L WW.USERPORT(A0) ,A0 

SYSLIB GETMSG ; MESSAGE SHOULD BE AVAILABLE AFTER 'WAITPORT' 

TST.L D0 ; POINTER TO INTUIMESSAGE COMES BACK IN D0 

BEQ.S LOOP ;NO MESSAGE FOUND THERE, SO LOOP (SHORT BRANCH) 

MOVE.L D0.A1 ; POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

MOVE.L IM. CLASS (A1),D2 ;CLOSEWINDOW AND MENUPICk MESSAGES APPEAR HERE 

MOVE.W IM.CODE(Al),D3 ;MENU AND MENUITEM APPEAR HERE 

MOVE.W IM.QUALIFIER(A1),D4 ,-KEYS APPEAR HERE 

SYSLIB REPLYMSG ; QUICK, SEND MESSAGE BACK NOW! 

CMP.L #CLOSEWINDOW,D2 ;COMPARE CONTENTS OF D2 WITH VALUE OF 'CLOSEWINDOW' 
BEQ.S PRINTMORE ;IF THEY'RE EQUAL, THIS IS A CLOSEWINDOW MESSAGEl 

BRA LOOP ; OTHERWISE, BRANCH ALWAYS (BRA) BACK TO LOOP 

;*** NOW PRINT MORE TEXT TO THE WINDOW *** 

PRINTMORE 
MOVE A. L WINDOW, A0 
LEA MESSAGE2.A1 
MOVE.L #10, D0 
MOVE.L #75, Dl 

BSR _PRINTTEXT ;USE SUBROUTINE TO PRINT TEXT TO WINDOW 

TST.L D0 
BEQ SKIPIT 
MOVE.L D0.MSG2 [SAVE ADDRESS OF INTUITEXT WHICH CAME BACK 
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SKIPIT 
MAKEITEX MESSAGES, ERR_D0NE,MSG3 ;USE MACRO TO MAKE AN INTUITEXT 
PRINTOLDAT WINDOW, MSG3 , 10, 90, ERR DONE ;PRINT FRESH INTUITEXT (ITS OLD NOW1 ) 



MOVE.L #TICKSPERSECOND,Dl 
DOSLIB DELAY 



; LEAVE IT THERE 1 SECOND 
>ELAY 

.*** N0W FINISH UP, CLOSE WINDOW, AND EXIT TO SKELETON *** 



DONE 

MOVEQ #0,D0 
ERR_DONE 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S QUIT 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
QUIT 

PULLREG D0 

RTS 

ERROR 
MOVEQ #21, D0 
RTS 



;NO ERRORS, SO PLACE IN D0 AS ERROR CODE 

;HIDE D0 FOR A MOMENT ON THE STACK 

; CHECK FOR AN OPEN WINDOW 

;IF 'WINDOW' = , THEN NO WINDOW WAS OPENED 

.•THERE IS A WINDOW 

;SO CLOSE IT 

; RESTORE D0 NOW 

; RETURN TO 'CLEANUP' PORTION OF SKELETON 



;PUT ERROR CODE #21, "CAN'T OPEN WINDOW" 
;EXIT TO SKELETON NOWI 



,*** DATA STORAGE *** 

MYWINDOWTITLE ; NULL-TERMINATED WINDOW TITLE TEXT 

DC.B ' WindowPrint by D. Wolf',0 

EVBNPC ; WORD-ALIGN MEMORY AFTER DC.B I 

MESSAGE 

DC.B ' This is an example of printing text using INTUITION ',0 

EVENPC 
MESSAGE 1 

DC.B ' And another example of Intuitext Printing ',0 

EVENPC 
MESSAGE2 

DC . B ' Here is some more ' , 

EVENPC 
MESSAGE3 

DC.B ' And even MORE ',0 

EVENPC 



WINDOW DC.L 
RP DC.L 
MSG DC.L 
MSG1 DC.L 
MSG2 DC.L 
MSG3 DC.L 

NEWWINDOW 
DC.W 40 
DC.W 15 
DC.W 500 
DC.W 120 
DC.B -1 
DC.B -1 
DC.L CLOSEWINDOW 

DC . L ACTIVATE I WINDOWSI Z ING 1 WINDOWDRAG I WINDOWDEPTH 1 WINDOWCLOSE I SMART_REFRESH 
DC.L fPOINTER TO FIRST USER-DEFINED GADGET 

DC.L ;POINTER TO USER-DEFINED CHECKMARK 

DC.L MYWINDOWTITLE ; POINTER TO TITLE TEXT 

; POINTER TO CUSTOM SCREEN 

; POINTER TO CUSTOM BITMAP 

;MINWIDTH 

;MINHEIGHT 

;MAXWIDTH 

;MAXHEIGHT 

;TYPE OF SCREEN THIS WINDOW IS IN 



.•STORAGE FOR POINTER TO THE WINDOW STRUCTURE 
; STORAGE FOR WINDOW'S 'RASTPORT' POINTER 
POINTERS FOR INTUITEXTS (TO USE WITH PRINTOLDAT) 



; NEWWINDOW STRUCTURE DECLARED DIRECTLY IN CODE 

•LEFTEDGE 

;TOPEDGE 

; WIDTH 

.•HEIGHT 

;DETAILPEN (= FF, MAXIMUM REGARDLESS OF SCREEN DEPTHl) 

; BLOCKPEN 



DC.L 

DC.L 

DC.W 50 

DC.W 20 

DC.W 640 

DC.W 400 

DC.W WBENCHSCREEN 

END 



U 
U 
U 
U 
U 
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Be sure you understand the concepts related to text han- 
dling by Intuition. The INTUITEXT structures are always used 
to embellish simple null-terminated text in Intuition applica- 
tions. Other Intuition features, such as menus and gadgets, 
also use INTUITEXT structures when they need text. When 
you use the familiar Amiga menus, be aware that each line of 
a menu also has its corresponding INTUITEXT structure. The 
concept is simple, but important, and comes up many times as 
we present more about the Intuition system features. The 
INTUITEXT structure contains the information required to 
color and style the text. 
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CHAPTER 18 U 

Intuition Menus \j 

The Amiga system that provides pull-down menus is extraor- ! I 

dinarily flexible. Users interact with menu selections using the 
mouse and its right button. Making a selection is as simple as 
releasing the button over the desired selection. Each menu 
item can hold either text or special imagery; or, it can be 
checkmarked or highlighted by changing color or having a box 
surround it when selected; or, it can show an alternate com- 
mand key. 

Controlling all this can become complex. As with win- 
dows, there's a family of flags for most menu features. Don't 
forget that each menu is attached to a window. The menu 
sends its event messages to your program by way of that win- 
dow's IDCMP Port. 

Each menu may have many menu items. The menu itself 
usually has a title shown at the top of the menu. Each menu 
item is usually represented by text specifying the action that 
will take place when that item is selected. You can create sev- 
eral menus next to each other, each with its own features. 

One drawback to using menus in a machine language 
program is that each item must have its own MENUITEM 
structure to specify how it is drawn, and each of these struc- 
tures must have substructures for INTUITEXT, or images used 
when that menu item is drawn. Declaring (and making sure 
their pointers all point correctly to other structures) all the 
MENU, MENUITEM, and INTUITEXT structures needed for | | 

just a small menu is a chore and can cause source code to bal- ~~" 
loon to an unmanageable size. 

Lj 

u 

LJ 
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Table 18-1. Intuition MENUITEM Structure 




Symbol: 


MI 






n 


Size: 34 


bytes ($22 bytes) 






Field Size Name 


Offset Description 


n 


Long 


MI.NEXT 





Pointer to next MENU- 
ITEM structure 


! 1 


Word 


MI.LEFTEDGE 


4 


Number of pixels from 
left edge 




Word 


MI.TOPEDGE 


6 


Number of pixels from 
top edge 




Word 


MI. WIDTH 


8 


Number of pixels wide 




Word 


MI.HEIGHT 


10 


Number of pixels high 




Word 


MI.FLAGS 


12 


Enable, render, and 
event flags 




Long 


MI.MUTUALEXCLUDE 14 


Bits excluding other 










menu items 




Long 


MI.ITEMFILL 


18 


Pointer to INTUITEXT or 
IMAGE structure 




Long 


MI.SELECTFILL 


22 


Pointer to select text or 
image 




Byte 


MI.COMMAND 


26 


A command key 




Long 


MI.SUBITEM 


28 


Pointer to subitem 
MENUITEM structure 




Word 


MI.NEXTSELECT 


32 


Menu number of simul- 
taneous selection 



n 

H 

n 
n 



One solution to this problem is to use routines needing 
only the text of each item and the menu title declared in the 
source code. That is, the philosophy behind the MENUS.ASM 
routines for this chapter. 

Listing 18-1 contains the code for the MENUS.ASM in- 
clude file which has subroutines and macros that dramatically 
simplify and shorten the code needed to work with Intuition 
menus. As with the type-in include files presented in earlier 
parts of this book, you should use EMACS or your favorite 
text editor to type in the file and save it on the DEV disk 
you're creating with the name: 

DEV:RAMIT/INCLUDES/MENUS.ASM 

This will add the MENUS.ASM program code and macros 
to your growing family of include files on your DEV disk. 
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Listing 18-1. MENUS.ASM Intuition Menus-Support Code and 
Macros 

»***•****••*•***•***•••********* MENUS . ASM 8 y DANIEL WOLF 

COPYRIGHT 1987 BY COMPUTE I BOOKS 

03/21/87 

;MENU SUPPORT ROUTINES 

MITEMLIST MACRO (MENU ITEM LIST FILLER 
LEA _POINTERLIST,A0 

MOVE.L #\1,(A0)+ .-ADDRESS OP FIRST ITEM (DOT 011) 

MOVE.L #\2,(A0)+ ;ADDRESS OF SECOND ITEM (OR 01 IF NO ITEM) 

MOVE.L #\3,(A0) + 
MOVE.L #\4,(A0)+ 
MOVE.L #\5,(A0)+ 
MOVE.L #\6,(A0)+ 
MOVE.L #\7,(A0)+ 

MOVE.L #\8,(A0) (ADDRESS OF SEVENTH ITEM (OR 01) 

MOVE.L #\1,D2 

BSR DOSTEXTLEN ;GET WIDTH OF FIRST ITEM 

ASL.L #3,D3 (NUM CHARACTERS * 8 

ADD.L #30, D3 ;ADD ROOM FOR ALT KEY AND CHEKMARK 

MOVE.L D3.D1 

MOVE.L #\9,D0 (NUMBER OF ITEMS -I 

ENDM 

MAKEMEN MACRO (ADDRESSES OF PARAMETERS 
LEA \1,A0 
LEA \2,A1 
LEA \3,A2 
BSR MAKEAMENU 
TST.L D0 
BNE \4 
ENDM 

MENUEVENT (SEPARATES MENU *, MENUITEM #, AND (UPROGRAMMIT) SUB ITEM # 
MOVE.L D0.D1 
ANDI.W #31, D0 
LSR.W #5,D1 
ANDI.W #63, Dl 
RTS 

CREATEMENU[ SUBROUTINE ENTER WITH POINTER TO MENU SIZED MEM BLOCK IN A0 
( POINTER TO MENU NAME INTUITEXT IN Al 

( POINTER TO FIRST MENUITEM IN A2 

( THIS ROUTINE FILLS THE MENU STRUCTURE WITH REASONABLE STUFF 

MOVE.W D0,MENU.LEFTEDGE(A0) 
MOVE.W D1,MENU.WIDTH(A0) 

MOVE.W THISFONTHITE,MENU.HEIGHT(A0) (USE DEFAULT TEXT HEIGHT FOR MENU 
MOVE.W TmENUENABLED, MENU. FLAGS (A0) (ENABLE THIS MENU AT ONCE 
MOVE.L Al, MENU. NAME (A0) (POINTER TO NULL-TERMINATED NAME TEXT 

MOVE.L A2,MENU.FIRSTITEM(A0) (POINTER TO FIRST MENUITEM STRUCTURE 

PUSHREG D0.A0 
LEA MITEMPTR.A0 
MOVE.L #8,D0 
CLRMITEMPTRS 
MOVE.L #0,(A0)+ 
SUBQ.L #1,00 
BNE.S CLRMITEMPTRS 
PULLREG D0,A0 
RTS 



U 
U 
U 



CREATEITEM 
MOVE.L A1,MI.NEXT(A0) (PTR TO NEXT MENU ITEM IN THIS MENU ITEM LIST 

MOVE.W #2,MI.LEFTEDGE(A0) (ITEM STARTS 2 PIXELS FROM LEFT EDGE 
MOVE.W D1,MI.TOPEDGE(A0) 
MOVE.W D2,MI.W1DTH(A0) (MENU ITEM IS D2 PIXELS WIDE 

MOVE.W _THISFONTHITE,MI.HEIGHT(A0) (MENU ITEM IS 9 PIXELS HIGH 

ADDI.W #2,MI.HEIGHT(A0) (**TRY ADJUSTING HERE I I 

BCLR #0, MI. HEIGHT (A0) | 

MOVE.W _THISMITEMFLAGS, MI. FLAGS (A0) U — ' 

MOVE.L D4,MI.MUTUALEXCLUDE(A0) (MUTUAL EXCLUDES FOR ITEM 
MOVE.L A2,MI.ITBMFILL(A0) (INTUITEXT STRUCTURE FOR ITEM 
MOVE.B D0, MI. COMMAND (A0) (COMMAND KEY FOR ITEM 
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MOVE.L #0,MI.SUBITEM(A0) ;NO SUBITEMS 
MOVE #0,MI.NEXTSELECT(A0) ;NO CONNECTIONS 
RTS 

MAKEAMENU 

;TAKES AN ARRAY OP 8 LONGWORD ADDRESSES OP TEXTS IN _POINTERLIST 

;ALLOCATES AND INITS UP TO 8 INTUITEXT STRUCTURES INTO _ITEXTPTR ARRAY 

;ALLOCATES AND INITS UP TO 8 MENUITEM STRUCTURES INTO _MITEMPTR ARRAY 

;ALSO USES ARRAY OF 8 COMMAND KEY *BYTES* IN _CMDKEYPTR 

fD0=NUMMENUITEMS 

;Dl=WIDTH OP MENUITEMS 

;A0=ADDR OP COMMAND KEY LIST 

;A1=ADDR OF MUTUAL EXCLUDES 

!A2=ADDR OP NULL TERMINATED TEXT MENU STRIP TITLE 

MOVE.L D0.NUMMENITEMS 
MOVE.W Dl, MENITEMWIDTH 
MOVE.L A0,~CMDKEYPTR 
MOVE.L Al,_MUEXPTR 
MOVE.L A2,_THISMENUTITLE 

MOVE.L D0,D7 

CMP.L #8,D7 

BGT ERR_MAKEAMENU ,-MORE THAN 8 TEXT STRUCTURES! ERROR! 

MOVEQ.L #0,D6 ; OFFSET OF POUR BYTES PER BIT OF D7 

NEXTMENTEXT 
~LEA _POINTERLIST,A0 

TST.L 0(A0,D6.L) ;IS THERE A TEXT POINTER HERE?? 

BEQ _ENDMAKEAMENU 

MOVEQ.L #0,D0 
MENUTEXTSIZE 

REMEMBERPUBMEM REMEMBERKEY, #SIZE. IT 

TST.L D0 

BEQ ERR MAKEAMENUMEM 

LEA _ITEXTPTR,A0 

MOVE.L D0,0(A0,D6.L) ;STASH PTR TO INTUITEXT STRUCT IN ITEXTPTR ARRAY 

MOVEQ.L #0,D0 
MENUITEMSIZE 

REMEMBERPUBMEM REMEMBERKEY, #SIZE. MI 

TST.L D0 

BEQ ERR_MAKEAMENUMEM 

LEA _MITEMPTR,A0 

MOVE.L D0,0(A0,D6.L) ;STASH PTR TO MENUITEM STRUCT IN MITEMPTR ARRAY 
MAKEAMENUITEM 

LEA _POINTERLIST,Al 

MOVEA.L 0(A1,D6.L),A1 ;A1 IS POINTER TO NULL-TERMINATED TEXT 

LEA _ITEXTPTR,A0 

MOVEA.L 0(A0,D6.L),A0 ;A0 IS POINTER TO AN INTUITEXT STRUCT IN MEM 

BSR CREATETEXT ;INIT THE INTUITEXT STRUCT FOR THIS MENUITEM 

ADDQ.L *4,D6 ;ADD 1 LONGWORD' S WORTH TO D6 INDEX POINTER 

DBRA D7, NEXTMENTEXT ; DEC/NOTBRANCH ALWAYS ON D7 AS COUNTER 

MOVE.L NUMMENITEMS.D7 

MOVEQ.L #0,D6 
- MOVEQ.L #0,D5 
I I _NEXTMENITM 
I J LEA _|4ITEMPTR,A0 

MOVEA.L 4(A0,D6.L),A1 ;A1=ADDR OP MEM ALLOCATED FOR NEXT MENUITEM 

MOVEA.L 0(A0,D6.L),A0 ;A0=ADDR OF MEM ALLOCATED FOR MENUITEM 

LEA _ITEXTPTR,A2 

n MOVEA.L 0(A2,D6.L),A2 ;A2=ADDR OF MEM ALLOCATED FOR INTUITEXT 

MOVEA.L CMDKEYPTR.A3 
MOVE.B 0TA3,D5.L),D0 ; D0=COMMAND KEY BYTE FROM _CMDKEYPTR ARRAY 

MOVE.W MENUHITPARAM.D1 iDl=CURRENT DISTANCE PROM TOP 

MOVE.W _MENITEMWIDTH,D2 ;D2=WIDTH OF THESE MENUITEMS 

n MOVEA.L MUEXPTR.A3 
MOVE.L 0TA3,D6.L),D4 ;D4=MUTUAL EXCLUDE FOR THIS ITEM 

BSR CREATEITEM 

ADD.W _THISFONTHITE,Dl ;ADD FONT HEIGHT TO DISTANCE FROM TOP 

ADDI.W #2,D1 ;ADD ADDITIONAL PIXELS CAUSE WE'RE PLACING 

BCLR.L #0,D.l .-GUARANTEE ITS AN EVEN NUMBER! I I 

n MOVE.W Dl.MENUHITPARAM ;TEXT 2 PIXELS IN FROM THE TOP IN THE 

ADDQ.L #4,D6 ; INTUITEXT STRUCTURE (CREATETEXT, ABOVE) 

ADDQ.L tl,D5 
DBRA D7,_NEXTMENITM 
_ENDMAKEAMENU 
, - ■ REMEMBERPUBMEM REMEMBERKEY, #SIZE. MENU 
' ' TST.L D0 
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BEQ.S ERR_MAKEAMENUMEM 

MOVE.L D0.D1 

MOVE.L D0.A0 

MOVEA.L _THISMENUTITLE,A1 

MOVEA.L _MITEMPTR,A2 

HOVEQ.L #0,D0 

MOVE.W D0,MENUHITPARAM 
RTS 



ERR_MAKEAMENUMEM 

MOVE.L #CANTALLOCMEM,D0 

RTS 
ERR_MAKEAMENU 

MOVE.L #1,D0 

RTS 



; POINTER TO ALLOCATED MEM FOR A MENU STRUCTURE 

[POINTER TO FIRST MENUITEM ALLOCATED 
.•RETURN WITH D0 = 'SUCCEED* 

Dl = PTR TO MENU STRUCTURE 
;AND ZERO OUT THE HEIGHT MEASURE FOR NEXT ONE 
[ CALLER CAN NOW PLACE LEFTEDGE IN D0 AND 
PLACE WIDTH IN Dl AND 
;CALL CREATEMENU 



[RETURN WITH D0 
, RETURN WITH D0 



♦CANTALLOCMEM* 

*FAIL* 



_ITEXTPTR [ARRAY OF 8 PTRS TO INTUITEXT STRUCTURES 

~DC.L 0,0,0,0,0,0,0,0 

MITEMPTR .-ARRAY OF 8 PTRS TO MENUITEM STRUCTURES 

DC.L 0,0,0,0,0,0,0,0 

POINTERLIST [PUT PTRS TO UP TO EIGHT LABELLED DC.B TEXTS HERE 

~DC.L 0,0,0,0,0,0,0,0 

CMDKEYPTR 
~DC.L 
MENUHITPARAM 

DC.W 
_MENITEMWIDTH (STORAGE FOR WIDTH MEASURE (WORD) 

DC.W 
NUMMENITEMS 

DC.L 1 
JTHISMENUTITLE 

DC.L 

MUEXPTR 
~DC.L 

THISMITEMFLAGS 



PUT PTR TO COMMAND KEY LIST FOR THESE MENUITEMS HERE 
KEEPS TRACK OF HEIGHT VALUE FOR SUCCESSIVE MENUITEMS 



;HOW MANY MENU ITEMS FOR THIS MENU 

[POINTER TO TITLE NULL-TERMINATED TEXT 

[POINTER TO LIST OF MUTUAL EXCLUDE VALUES FOR MENITEMS 

(DEFAULT MENU ITEM FLAGS 



DC.W CHECKITIHIGHCOMPICOMMSEQI ITEMENABLED1 ITEMTEXT 



The MAKEAMENU, CREATEMENU, and CREATITEM 
subroutines. These subroutines can take the drudgery out of 
menu programming. They permit you to declare the text re- 
quired for your menus, and then allocate and fill MENU, 
MENUITEM, and INTUITEXT structures. The structures are 
filled with standard default values shown in the listings. You 
can change them in the declarations or with your own code. 
Note the FLAGS settings, specifically, because those are the 
ones to alter for experimentation. 

The most complex structure in the menu is the 
MENUITEM structure (Table 18-2). One MENUITEM structure 
is created and filled for each selection on the menu. This is 
difficult to do with an algorithm that will satisfy all program- 
mers, so don't consider CREATITEM to be "the last word" in 
subroutines. You will Undoubtedly want to do some experi- 
mentation and tailor it to fit your individual needs. 

MAKEAMENU does some arithmetic to assure that the 
INTUITEXT structures (which are linked to each MENUITEM 
structure) are positioned properly. The settings used in these 
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routines also specify CHECKMARK, assume you are supplying 
command keys to allow keyboard selection as well as mouse 
selection, HIGHCOMP (video reverse highlighting of selected 
Menu items), default font, JAM1 drawing mode, and so on. 
These default selections will be acceptable on most applica- 
tions, but you're encouraged to alter the FgPen and BgPen 
settings, swap JAM2 for JAM1, use HIGHBOX instead of 
HIGHCOMP as the highlight mode, and so on. 

The only limitation inherent in the routines as they are 
written is that MAKEAMENU only accepts up to eight items 
per menu. Changing that limit is easy, and it's a good pro- 
gramming exercise. If you want multiple menus, the program 
must link the NEXTMENU fields of the MENU structures, and 
must also arrange them so that the menus are positioned ap- 
propriately across the screen. The examples show both single 
and multiple menu usage (Listings 18-2 and 18-3, 
MENU1.ASM and MENU2.ASM). 

The MAKEPTRLIST and MAKEMEN macros. Like the 
other Intuition include files presented in this book, the 
MENUS. ASM file also has macros that call the subroutines in 
the file and make program coding even more efficient than 
using the subroutines themselves. In this file, there are two 
macros to shorten the programming chores. Their use is illus- 
trated in the example programs of Listings 18-2 and 18-3. 

Programming Menus with the Support Routines 

The application program must do several things to take advan- 
tage of the MAKEAMENU subroutine: 

• Declare text strings using labels 

• Setup _POINTERLIST with pointers to the labels (use the 
macro) 

• Setup address registers with pointers to command key defini- 
tions, mutual excludes, and the title text 

• Setup data registers with count and MENUITEM position 
information 

• BSR MAKEAMENU (this produces the list of MENUITEM 
structures) 

• Check for errors (this and the previous two tasks are per- 
formed by the MAKEMEN macro) 

• Save the pointer to the MENU structure returned by 
MAKEAMENU 
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• Setup data registers for actual MENU position 

• BSR CREATEMENU (this finalizes filling in the MENU 
structure) 

• Repeat each of the above steps for each additional MENU 
required 

• Link NEXTMENU fields of the MENU structures obtained 

• Place address of the WINDOW structure into address register 
AO 

• Place address of the first MENU structure into Al 

• Call the Intuition routine SETMENUSTRIP to attach the 
menus to the window 

The preparation for MAKEAMENU and CREATEMENU 
takes several lines of code in most cases, but this is much 
shorter than declaring the structures directly. The macros elim- 
inate this chore. MAKEAMENU and CREATEMENU allocate 
memory, using the ALLOCREMEMBER function, so that all 
memory used by all the menu-related structures can be re- 
turned to the system at once with FREEREMEMBER, at the 
end of the program. 

Public memory is used for these structures because they 
aren't absolutely required to reside in chip memory. Public 
memory allocation will first try to use any fast (or expansion) 
memory attached to the Amiga. This is a friendly way to coex- 
ist with the multitasking Executive, since all memory required 
for use with the structures is allocated in small chunks "on the 
fly" and scarce chip memory is conserved wherever possible. 

When first implemented, these routines were used to re- 
place a declaration of a four-item menu. There was a savings 
of nearly 2K in the source listing and hundreds of bytes in the 
assembled program (even though the routines themselves add 
to program size). 

The MAKEAMENU subroutine (CREATEITEM, 
CREATETEXT). MAKEAMENU utilizes two additional 
routines to prepare a set of MENUITEM structures and their 
associated INTUITEXT structures, for a complete menu of up 
to eight items. 



U 
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The CREATEITEM routine is called to fill in the 
MENUITEM structure allocated by MAKEAMENU. The 
CREATETEXT routine is called to fill the INTUITEXT structure 
allocated for each of the MENUITEM structures. 
MAKEAMENU allocates memory for the structures, including 
the final MENU structure, which points to the first 
MENUITEM structure. In addition, MAKEAMENU assures 
that text is positioned correctly within the menu selection 
strips. 

MAKEAMENU links pointers among the structures, as 
well. When MAKEAMENU returns, it either supplies an ad- 
dress to a MENU structure (if it was successful), or returns an 
error code. It does not actually fill in the MENU structure be- 
cause when several menus are made, they must be positioned 
correctly with data supplied from the application program. 
The final job of filling in the MENU structure is left to a later 
call to CREATEMENU. 

Before exploring the other intricacies of Intuition menu 
programming, you should try the MENU1.ASM program in 
Listing 18-2. It pulls together the concepts presented so far 
and shows the use of the MENUS.ASM support code routines 
and macros. 

Listing 18-2. MENU1.ASM 

This program creates a single menu with three items. 

##;MENU1.ASM BY DANIEL WOLF 

[COPYRIGHT 19B7 BY COMPUTEl PUBLICATIONS 

;09/10/87 

BRA _START 

DOS EQU 1 
INT EQU 1 
GFX EQU 1 

WIN EQU 1 
MEN EQU 1 
TXT EQU 1 

INCLUDE "HEADER" 

MAIN 

TST.L ENDPROMWB ;IF INITIATED FROM WB, THEN NO ANNOUNCEMENTS YETI 

BNE.S _BUILDAWINDOW 
FROMUSER 

DOSPRINT STDOUT, #MYMESSAGE ;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 

MOVEQ #0,D0 

MOVE A. L COMMAND, A0 ;PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'?",(A0) jIF FIRST CHARACTER IS ? THEN 

BNE.S BUILDAWINDOW 

BRA USAGE ; PRINT OUT INSTRUCTIONS AND QUIT 

_BUILDAWINDOW 

MAKEWIN #MYWINDOWTITLE , 40 , 15 , 500 , 160 , ERROR 

MOVE.L D0, WINDOW ; WINDOW OPENED HAS ITS POINTER IN D0 
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BUILDMENU 
"LEA _POINTERLIST,A0 
MOVE.L #MYITEM0, (A0)+ 
MOVE.L #MYITEM1,(A0)+ 
MOVE.L #MYITEM2,(A0)+ 
MOVE.L #2,D0 



;THE FIRST OF A BLOCK OF 8 POINTERS 
(FILL BLOCK WITH POINTERS TO MENU ITEM TEXTS 
(THESE ARE MOVES OF THE ADDRESSES OF MYITEM0 
(INTO THE FIXED ARRAY FOR 'MAKEAMENU' 
(NUMBER OF MENUITEMS FOR THIS MENU 



(MITEMLIST MYITEM0,MYITEM1,MYITEM2,0,0,0,0,0,2 



(MACRO FOR LAST 6 LINES 



MOVE.W #120, Dl 
LEA MYCMDKEYS.A0 
LEA MYMUEXES.A1 
LEA MYMENUTITLE.A2 
BSR MAKEAMENU 
TST.L D0 
BNE DONE 



(WIDTH OF MENUITEMS FOR THIS MENU 
(ADDR OF COMMAND KEY LIST FOR THIS MENU 
(ADDR OF MUTUAL EXCLUDES FOR THIS MENU 
(ADDR OF TITLE FOR THIS MENU 

(ALLOCATE AND BUILD MENUITEM STRUCTURES 
(ALL'S WELL? 



I MAKEMEN MYCMDKEYS , MYMUEXES , MYMENUTITLE , DONE 



(MACRO FOR LAST 6 LINES 



(MAKEAMENU RETURNS WITH POINTER TO MENU IN Dl 

(LEFEDGE FOR THIS MENU 

(WIDTH FOR THIS MENU 

(THIS CREATES THE ACTUAL MENU ATTACHED TO THE ITEMS 



(SUPPLY POINTER TO WINDOW IN A0 
(SUPPLY POINTER TO MENU #0 IN Al 
(AND ATTACH THE MENU TO THE WINDOW 



MOVE.L D1,_THISMENU 
MOVE.W #5,D0 
MOVE.W #120,D1 
BSR CREATEMENU 

_MENUATTACH 
MOVE.L WINDOW, A0 
MOVE.L THISMENU.A1 
INTLIB SETMENUSTRIP 

MOVE.L #TICKSPERSEC0ND,D1 
DOSLIB DELAY 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L #?FFFF,D0 
INTLIB ONMENU 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S RELOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.C0DE(A1),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L #CLOSEWINDOW, D2 

BEQ DONE 

CMP.L #MENUPICK,D2 

BNE RELOOP 

MOVEQ.L #0,D0 

MOVE.W D3.D0 

BSR MENUEVENT 

TST.W D0 

BNE HANDLEMENU1 

CMPI.W #2,D1 

BEO DONE 

CMPI.W #1,D1 

BEQ.S DOITEM1_MENU0 

CMPI.W #0,D1 

BEQ.S DOITEM0_MENU0 

BRA.S RELOOP 
DOITEM1_MENU0 

BSR MENU0ITEM1 

BRA.S RELOOP 
DOITEM0_MENU0 

BSR MENU0ITEM0 



HANDLEMENU1 
(INTERCEPT MENU1 AND ITS MENUITEMS HERE, IF THEY EXIST 



(SET UP 1 SECOND'S WORTH OF TICKS 
(LET THE TIMER TICK DOWN TO ZERO 



;WAKE UP THE WHOLE MENU NOW 



r LISTEN TO PORT ATTACHED TO THIS WINDOW 
(WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



(MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

(POINTER TO INTUIMESSAGE COMES BACK IN D0 

(NO MESSAGE THERE, SO LOOP 

(POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

(CLOSEWINDOW AND MENUPIC MESSAGES APPEAR HERE 

(MENU AND MENUITEM APPEAR HERE 

(KEYS APPEAR HERE 

(QUICK, SEND MESSAGE BACK N0W1 



(IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO... 

(THIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 

(SETUP MENUCODE IN D0 FOR THIS SUBROUTINE 

(D0 IS THE MENU NUMBER 

(IF THIS ISN'T MENU #0, THEN CHECK IF MENU #1 

(Dl IS THE MENUITEM NUMBER, SEE IF Dl = 2 

(IF MENUITEM = 2 THEN *QUIT* 

(COMPARE IMMEDIATE, SEE IF Dl = 1 

(IF MENUITEM = 1 THEN DO *ITEM1* MENU0 

(COMPARE IMMEDIATE, SEE IF Dl = 

(IF MENUITEM = THEN DO *ITEMO* MENU0 

(IF NONE OF ABOVE, THEN LOOP 



RELOOP 
BRA LOOP 



(RETURN TO TOP OF LOOP AND SCAN FOR MESSAGES 
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DONE 

MOVE.L WINDOW, D0 

BEQ.S QUIT 

MOVE.L D0.A0 

INTLIB CLEARMENUSTRIP 
QUIT 

MOVEQ.L #0,D0 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1$ 

PULLREG D0 
QUITNOW 

RTS 



ERROR 
DOSPRINT STDOUT, #ERRORTEXT 
MOVE.L #21, D0 
BRA QUITNOW 

USAGE 
DOSPRINT STDOUT, tUSAGETEXT 
BRA DONE 

MENU0ITEM1 
MOVE.L WINDOW, A0 
BSR _CLEARWINDOW 
RTS ~ 

MENU0ITEM0 

MOVE.L WINDOW, A0 
MOVE.L #3,D0 
BSR _FILLWINDOW 
RTS ~ 



;NOW CLEAN UP WINDOW AND EXIT 



(MUST CLEAR THE MENU PRIOR TO CLOSING WINDOW 



1$ IS A LOCAL LABEL A NUMBER? LABEL IS LOCAL 
MEANING IT CAN BE USED BETWEEN TWO REGULAR LABELS 
MEANING THE SAME LABEL CAN BE USED MANY TIMES 
BUT EACH TIME WITH A DIFFERENT 'LOCAL' MEANING 



! USING DOS TO PRINT MESSAGE TO CLI WINDOW 



[USING DOS TO PRINT MESSAGE TO CLI WINDOW 



;CLEAR THE WINDOW, NO COLOR JUST BACKGROUND 



;FILL WITH COLOR 

(PUT WINDOW POINTER IN A0 

; COLOR REGISTER SELECTION (0-3 ON WORKBENCH) 

; FILL THE WINDOW 



MYWINDOWTITLE 

DC.B ' Menul by D.WOLF ',0 

EVENPC 
USAGETEXT 

DC.B 'Usagei Menul', 10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MYMESSAGE 

DC.B 10,'Monul by Daniel Wolf Copyright 1987 by Computel Publications' ,10,0 

EVENPC 



WINDOW DC.L 
RP DC.L 
_THISMENU 
DC.L 

MYMENUTITLE 

DC.B 'MENU EXAMPLE', 

EVENPC 
MYITEM0 

DC.B ' ITEM A ' ,0 

EVENPC 
MYITBM1 

DC . B ' ITEM B ' , 

EVENPC 
MYITEM2 

DC.B ' QUIT ',0 

EVENPC 
MYCMDKEYS 

DC.B 'ABQ' 

EVENPC 
MYMUEXES 

DC.L 6,5,0 

EVENPC 
_THISFONTHITE 

DC.W 9 



[POINTER TO WINDOW STRUCTURE 

[POINTER TO WINDOW'S RASTPORT STRUCTURE 

[POINTER TO 'FIRST' MENU STRUCTURE 

[TEXT FOR MENU TITLE 

[TEXT FOR FIRST MENUITEM, WITH ROOM FOR CHKMARK 

[TEXT FOR SECOND MENUITEM 

(TEXT FOR THIRD MENUITEM 

[LIST OF 'COMMSEQ' MENU ALTERNATE COMMAND KEYS 

(LIST OF MUTUAL-EXCLUDE VALUES TO RESTRICT 
[CHECKMARK TO ONE ITEM AT A TIME 
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The MENU1.ASM program demonstrates some previously 
unexplained menu features. 

The CREATEMENU and MAKEAMENU routines use 
standard values for some important flags that control how the 
menus appear and operate. You can think of these flags like 
WINDOW flags or IDCMP flags, but they control menu features. 

Since these flags are specified by the routines in the 
MENUS. ASM file, they're hidden from the MENU1.ASM pro- 
gram. If you wish to manipulate them to vary the appearance 
and control features of your menus/you'll have to change the 
MENUS.ASM file or modify them after the menu has been 
created by your program. This can be done with code that 
looks up the flags within a MENU structure. Such changes 
should be made prior to actually calling the Intuition library 
SETMENUSTRIP function. 

The MENUITEM flags. There are 12 flag bits that can be 
set prior to a call to MAKEAMENU. They control the actual 
MENUITEM structures and the appearance and use of menu 
items. These are set to default values in the MENUS.ASM in- 
clude file for this chapter, but can easily be altered for experi- 
mentation (strongly encouraged due to the variety of combi- 
nations). A list of them is in Table 18-2. 
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Table 18-2. The MENUITEM Hags 




Name 


Bit Value 


Description 




CHECKIT 


$0001 


Setting this flag informs Intuition 
that this is an attribute item, rather 
than an action item 




ITEMTEXT 


0002 


This flag is set if item is text, clear if 
its an image 




COMMSEQ 


0004 


Set if a command key is supplied for 


u 






the item 


MENUTOGGLE 


0008 


Toggles the checkmark when 
selected 




ITEMENABLED 


0010 


Set to enable this menu item's 


u 






messages 


HIGHIMAGE 


0000 


Displays user's select image when 








selected 


u 


HIGHCOMP 


0040 


Highlights selected item by comple- 






menting it 




HIGHBOX 


0080 


Highlights selected item with a box 
border 


u 


HIGHNONE 


ooco 


No highlighting at all 


u 
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Name Bit Value Description 

CHECKED 0100 If CHECKIT is specified, Intuition 

sets this when item is selected 
ISDRAWN 1000 Set by Intuition if subitems shown 

HIGHITEM 2000 Set by Intuition if item is highlighted 

MENUTOGGLED 4000 Set by Intuition if item already 

toggled 

Once again, a program can combine these using the ! (log- 
ical OR) assembler directive. Use the examples and experiment 
with other combinations of the flags, and try resetting the 
flags for a second menu. 

The MUTUALEXCLUDE bits. You may make a menu 
even more intelligent by proper use of the MUTUALEXCLUDE 
feature for each MENUITEM. MUTUALEXCLUDE is used to 
indicate that selecting a menu item automatically deselects an- 
other menu item. This is like the buttons on a car radio. If you 
push a button to select a station, the old button gets "popped" 
back out. 

A long word (32 bits) is used to specify a MUTUAL- 
EXCLUDE pattern. Two attribute menu items that have differ- 
ent MUTUALEXCLUDE fields will automatically deselect each 
other. For example, lets say your writing a printing program. 
In one menu, you want two menu items, "Letter Quality" and 
"Draft". Since printing in draft and letter quality mode are 
exclusive of each other, you can indicate this with their 
MUTUALEXCLUDE flags. Set a MUTUALEXCLUDE flag of 
$00 for the "Letter Quality" menu item and a flag of $01 for 
the "Draft" menu item. Selecting "Draft" will now automati- 
cally deselect "Letter Quality", and vice versa. 

When MAKEAMENU is called, one parameter supplied is 
a pointer to a list of MUTUALEXCLUDE values for the associ- 
ated list of menu items. MAKEAMENU expects you to declare 
the MUTUALEXCLUDE values with a labeled DC.B string of 
bytes. Examine the code examples for more instances of how 
the MUTUALEXCLUDE feature is utilized. 
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The Command Key Feature 

A command key selects a menu item, when pressed while 
holding down one of the AMIGA keys. Each menu item may 
be selected by a keypress, or with the mouse, if the program- 
mer allows for this option by including certain information in 
the MENUITEM structure. The MENUITEM must have its 
COMMSEQ flag set to a value of 1, and a command key byte 
must be supplied. The user can then activate that menu item 
by pressing an AMIGA key and the specified command key 
together. 

The code examples below utilize a string of byte values 
for the command keys associated with a list of menu items. 
When MAKEAMENU is called, one of the parameters supplied 
is the pointer to your list of command key definitions for that 
menu item list. Declare them with a labeled DC.B string of 
characters (see the examples). 

Figure 18-1 may help you to understand the mutual exclude 
and command key features. 

Figure 18-1. Screen, Window, Menu with Menu Items, Mutual 
Excludes, and Command Keys 
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The CREATEMENU subroutine. This routine's purpose 
is to fill in the MENU structure allocated by MAKEAMENU. 
It's possible to adjust the flags field and variables relating to 
position, prior to this call, which finishes the process that cre- 
ates the menu. 

MENU structure flags. You can program a flag bit to en- 
able a menu, or you can examine the flag bit to see if the 
menu is enabled. This flag bit can be manipulated in program 
code and also by Intuition. The other flag bit is set by Intu- 
ition if the menu is being shown on the screen. Here is a list 
of the flag bits and their values and descriptions: 



Flag Bit 

MENUENABLED 



Bit Value Description 

$0001 Read/ write flag, indicates or sets 
whether MENU is on or off 
MIDRAWN 0004 Set by Intuition if menu is showing 

The full Menu Structure is defined in Table 18-3. 
Table 18-3. Intuition MENU Structure 



Symbol: 


MENU 






Size: 30 


bytes ($1D bytes) 






Field Size Name 


Offset Description 


Long 


MENU.NEXT 





Pointer to next MENU 
structure 


Word 


MENU.LEFTEDGE 


4 


Number of pixels from 
left edge 


Word 


MENU.TOPEDGE 


6 


Number of pixels from 
top edge 


Word 


MENU.WIDTH 


8 


Number of pixels wide 


Word 


MENU.HEIGHT 


10 


Height of one menu item 


Word 


MENU.FLAGS 


12 


Menu enabled, menu 
item drawn 


Long 


MENU.MENUNAME 


14 


Pointer to null- 
terminated title text 


Long 


MENU.FIRSTITEM 


18 


Pointer to first 
MENUITEM structure 


Word 


MENU.JAZZX 


22 


System use only 


Word 


MENU.JAZZY 


24 


System use only 


Word 


MENU.BEATX 


26 


System use only 


Word 


MENU.BEATY 


28 


System use only 
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The MENU 1. ASM program (Listing 18-2) shows a three- 
item menu added to a window. The first two items are dum- 
mies with no effect, and the last one is a QUIT option, which 
has the same effect in the program as clicking on the 
CLOSEWINDOW gadget. Notice once again how the IDCMP 
communications loop uses its analysis of the MENUPICK mes- 
sage to get the class (menu and menu item numbers). The 
MENUEVENT subroutine is a short one that extracts the com- 
bined numbers and provides them back to the program, sepa- 
rately, in registers DO and Dl. MENU2.ASM is a program 
example showing two complete multiitem menus. The code 
demonstrates how they become linked into a unified menu for 
the program. 

The MENUEVENT subroutine. This routine is provided 
to extract the menu number, menu item number, and (if you 
use them) subitem number in separate registers. 

The INTUIMESSAGE that occurs (when the MENUPICK 
IDCMP flag on an open window is set) combines all the num- 
bers into one. They reside in three groups of five bits each. 
There can be up to 32 of them. The MENUEVENT subroutine 
separates these values for use by the program code. The pro- 
gram example shows how it is used. 

NOTE: In order to receive messages about menu selec- 
tions, you must include the MENUPICK flag bit in your win- 
dows IDCMP Port. 

Removing a Menu 

When a program needs to switch menus or remove a menu 
from the title bar, a call is made to CLEARMENUSTRIP, an 
Intuition library function. You must call this function before 
closing any window that has a menu attached. 

The listings below, MENU1.ASM and MENU2.ASM, show ' — ' 
how to clear a menu before closing a window. To replace one 
menu entirely with another, use CLEARMENUSTRIP to elimi- i 

nate the first menu before creating and attaching the new menu. 
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To round out this introduction to Intuition menus, Listing 
18-3 contains an example of a menu strip with two menus. 
Each MENU structure has a set of menu items and its own ti- 
tle. Prior to calling SETMENUSTRIP in the Intuition library, 
insure that the first MENU structure points to the next MENU 
structure: Place the address of the second MENU structure in 
the NEXT field of the first. Then, SETMENUSTRIP makes 
both menus available at once. 

Listing 18-3. MENU2.ASM 

Example program with two menus of three items each. 

ft #; MENU 2. ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 

;09/10/87 

BRA _START 

DOS EQU 1 
INT EQU 1 
GPX EQU 1 

MEN EQU 1 
TXT EQU 1 
WIN EQU 1 

INCLUDE "HEADER" 

MAIN 

TST.L ENDFROMWB ;IF INITIATED FROM WB, THEN NO ANNOUNCEMENTS YET1 

BNE.S _BUILDAWINDOW 
FROMUSER 

DOSPRINT STDOUT,#MYMESSAGE ;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 

ZERO D0 

MOVEA.L COMMAND, A0 ;PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'7',(A0) ;IF FIRST CHARACTER IS 7 THEN 

BNE.S _BUILDAWINDOW 

BRA USAGE ; PRINT OUT INSTRUCTIONS AND QUIT 

_BUILDAWINDOW 
MAKEWIN #MYWINDOWTITLE , 40 , 1 5 , 500 , 160 , ERROR 
MOVE.L D0, WINDOW ; WINDOW OPENED HAS ITS POINTER IN D0 

MOVE.L D0,A0 ;PUT WINDOW POINTER IN A0 

BSR _CLEARWINDOW [CLEAR THE WINDOW, NO COLOR JUST BACKGROUND 

.«** N0W hake tvjq MENUS USING MACROS FROM MENUS. ASM SUPPORT FILE *** 

_BUILDMENU 
MITEMLIST MYITEM0,MYITEM1,MYITEM2,0,0,0,0,0,2 
MAKEMEN MYCMDKEYS , MYMUEXES , MYMENUTITLE , DONE 
MOVE.L D1,_THISMENU 
MOVE.L #5,D0 
MOVE.W #120, Dl 
BSR CREATEMENU 
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_BUILDMENU2 
MITEMLIST MYITEM02,MYITEM12, 0,0, 0,0, 0,0,1 
MAKEMEN MYCMDKEYS , MYMUEXES , MYMENUTITLE2 , DONE 
MOVE.L D1,_THISMENU2 

MOVE.W #125, D0 ;LEFEDGE FOR THIS MENU (MOVED OVER FOR FIRST MENU) 

MOVE.W #120, Dl ;WIDTH FOR THIS MENU 

BSR CREATEMENU 



_LINKMENUS 
MOVEA.L TBISMENU.A0 
MOVE.L _THISMENU2,D0 
MOVE.L D0,(A0) 

_MENOATTACH 
MOVE.L WINDOW, A0 
MOVE.L _THISMENU,A1 
INTLIB SBTMENUSTRIP 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L #SFFFF,D0 
INTLIB ONMENU 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ RELOOP 
MOVE.L D0.A1 
MOVE.L IM.CLASS(A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L fCLOSEWINDOW, D2 

BEQ DONE 

CMP.L #MENUPICK,D2 

BNE RELOOP 

MOVEQ.L #0,D0 

MOVE.W D3.D0 

BSR MENUEVENT 

TST.W D0 

BNE HANDLEMENU1 

CMPI.W #2,D1 

BEQ DONE 

CMPI.W #1,D1 

BEQ.S DOITEM1_MENU0 

CMPI.W #0,D1 

BEQ.S DOITEM0_MENU0 

BRA.S RELOOP 
OOITEM1_MENU0 

BSR MENU0ITEM1 

BRA.S RELOOP 
DOITEM0_MENU0 

BSR MENU0ITEM0 

BRA.S RELOOP 

HANDLEMENU1 

CMPI.W #0,D1 

BEQ DOITEM0_MENU1 

CMPI.W #1,D1 

BEQ D0ITEM1_MENU1 

BRA.S RELOOP 
DOITEM0_MENU1 

BSR MENU1ITEM0 

BRA.S RELOOP 
D01TEM1_MENU1 

BSR MENU1ITEM1 



RELOOP 
BRA LOOP 



;PUT _THISMENU2 AS POINTER TO 'NEXT' MENU 



; SUPPLY POINTER TO WINDOW IN A0 
f SUPPLY POINTER TO MENU #0 IN Al 
;AND ATTACH THE MENU TO THE WINDOW 



;WAKE UP THE WHOLE MENU NOW 



; LISTEN TO PORT ATTACHED TO THIS WINDOW 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



; MESSAGE HAS ARRIVED WITHIN SPECIFICATIONS 

; POINTER TO INTUIMESSAGE COMES BACK IN D0 

;N0 MESSAGE THERE, SO LOOP 

; POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

;CLOSEWIND0W AND MENUPIC MESSAGES APPEAR HERE 

;MENU AND MENUITEM APPEAR HERE 

;KEYS APPEAR HERE 

; QUICK, SEND MESSAGE BACK N0W1 



;IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO... 

;THIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 

; SETUP MENUCODE IN D0 FOR THIS SUBROUTINE 

;D0 IS THE MENU NUMBER 

.-IF THIS ISN'T MENU #0, THEN CHECK IF MENU #1 

;D1 IS THE MENUITEM NUMBER, SEE IF Dl = 2 

;IF MENUITEM = 2 THEN *QUIT* 

.•COMPARE IMMEDIATE, SEE IF Dl = 1 

;IF MENUITEM = 1 THEN DO *ITEM1* MENU0 

.■COMPARE IMMEDIATE, SEE IF Dl = 

;IF MENUITEM = THEN DO *ITEM0* MENU0 

;IF NONE OF ABOVE, THEN LOOP 



.•INTERCEPT IF MENU = 1 
;SEE IF MENUITEM = 
;SEE IF MENUITEM = 1 



; RETURN TO TOP OF LOOP AND SCAN FOR MESSAGES 



u 
u 
u 
u 

% _ 

u 
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DONE 

MOVE.L WINDOW, D0 

BEQ.S QUIT 

MOVE.L D0,A0 

INTLIB CLEARMENUSTRIP 
QUIT 

ZERO D0 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0.A0 ; 

INTLIB CLOSEWINDOW 
15 

PULLREG D0 
QUITNOW 

RTS 

ERROR 
DOSPRINT STDOUT,#ERRORTEXT 
MOVE.L #21, D0 
BRA QUITNOW 

USAGE 
DOSPRINT STDOUT,#USAGETEXT 
BRA DONE 

MENU0ITEM1 
MOVE.L WINDOW, A0 
BSR _CLEARWINDOW 
RTS 

MENU0ITEM0 
MOVE.L WINDOW, A0 
MOVE.L #3,D0 
BSR _FILLWINDOW 
RTS 

MENU1ITEM0 

RTS 
MENU1ITEM1 

RTS 

MYWINDOWTITLE 
DC.B ' Menu2 by D. Wolf ',0 
EVENPC 

USAGETEXT 

DC.B 'Usage: Menu2',10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MYMESSAGE 

DC.B 10,'Menu2 by Daniel Wolf Copyright 1987 by Compute I Publications ',10,8 
EVENPC 



;NOW CLEAN UP WINDOW AND EXIT 



;MUST CLEAR THE MENU PRIOR TO CLOSING WINDOW 



1$ IS A LOCAL LABEL A NUMBERS LABEL IS LOCAL 
MEANING IT CAN BE USED BETWEEN TWO REGULAR LABELS 
MEANING THE SAME LABEL CAN BE USED MANY TIMES 
BUT EACH TIME WITH A DIFFERENT 'LOCAL' MEANING 



; USING DOS TO PRINT MESSAGE TO CLI WINDOW 



; USING DOS TO PRINT MESSAGE TO CLI WINDOW 



; CLEAR THE WINDOW, NO COLOR JUST BACKGROUND 



;FILL WITH COLOR 

• PUT WINDOW POINTER IN A0 

; COLOR REGISTER SELECTION (0-3 ON WORKBENCH) 

;FILL THE WINDOW 



WINDOW DC.L 
RP DC.L 

THISMENU 
"DC.L 
JTHISMENU2 

DC.L 
MYMENUTITLE 

DC.B 'MENU EXAMPLE', 

EVENPC 
MYITEM0 

DC.B ' ITEM A ',0 

EVENPC 
MYITEM1 

DC . B ' ITEM B ' , 

EVENPC 
MYITEM2 

DC.B ' QUIT ',0 

EVENPC 
MYCMDKEYS 

DC.B 'ABQ' 

EVENPC 



.•POINTER TO WINDOW STRUCTURE 

; POINTER TO WINDOW'S RASTPORT STRUCTURE 

; POINTER TO 'FIRST' MENU STRUCTURE 

; POINTER TO 'SECOND' MENU STRUCTURE 

;TEXT FOR MENU TITLE 

•TEXT FOR FIRST MENUITEM, WITH ROOM FOR CHKMARK 

j TEXT FOR SECOND MENUITEM 

•TEXT FOR THIRD MENUITEM 

;LIST OF 'COMMSEQ' MENU ALTERNATE COMMAND KEYS 
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MYMUEXES 
DC.L 6,5,0 
EVENPC 

MYMENUTITLE2 

DC.B ' EXAMPLE2 ' ,0 

EVENPC 
MYITEM02 

DC.B ' HELLO ',0 

EVENPC 
MYITEM12 

DC.B ' GOODBYE ',0 

EVENPC 
MYCMDKEYS2 

DC.B 'HO' 

EVENPC 
MYMUEXES 2 

DC.L 2,1 

THISPONTHITE 
~DC.W 9 
END 



;LIST OF MUTUAL-EXCLUDE VALUES TO RESTRICT 
; CHECKMARK TO ONE ITEM AT A TIME 



(TEXT FOR MENU TITLE 



[TEXT FOR FIRST MENUITEM, WITH ROOM FOR CHKMARK 



[TEXT FOR SECOND MENUITEM 



[LIST OF 'COMMSEQ' MENU ALTERNATE COMMAND KEYS 



[LIST OF MUTUAL-EXCLUDE VALUES TO RESTRICT 
[CHECKMARK TO ONE ITEM AT A TIME 



CJ 

u 
u 



222 



u 
u 

u 
u 



H 

n 
n 

n 

n 



CHAPTER 19 

Intuition Gadgets 



The Intuition gadget system provides many ways to communi- 
cate with an application. Gadgets are dedicated regions of 
windows that act like buttons, knobs, slide controls, and 
switches when the mouse is clicked in them. 

You're probably familiar with some of the built-in win- 
dow gadgets like the drag bar, sizing gadget, close gadget, and 
front/back gadgets. Programmable gadgets can have special 
imagery, coloring, or text to attract the user's attention and ex- 
plain their function. 

Gadgets can substitute for menus. Sometimes they make 
options more prominent to the user than a menu would. 

Producing effective gadgets takes planning and knowl- 
edge of the Intuition GADGET structure. The GADGET struc- 
ture is linked to text, border outlines, icon-like imagery, and 
other substructures by way of pointers. 

Types of Gadgets 

There are four types of gadgets: 

• Boolean gadgets 

• String gadgets 

• Proportional gadgets 

• Integer gadgets 

The integer gadget is actually a special type of string 
gadget. 

Boolean gadget. The Boolean gadget acts like an on/off 
switch. The user can activate it and deactivate it by clicking 
the left mouse button while the pointer is touching the gadget. 
The GADGET structure should have flags set to communicate 
the event to the application. If these flags are set, the applica- 
tion should test for receipt of GADGETUP and GADGETDOWN 
messages. 
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String gadget. The string gadget allows the user to edit r ~> 

and enter a text string. The text string can provide user input |_^J 

for file names, numerical values, and so on. When the amount 
of text input needed from the user, by a program, is limited, r~> 

string gadgets provide a handy text entry for the user. j^J 

Integer gadget. The integer gadget allows the user to edit 
and enter a numerical whole-number value 0-65535 in a way ,- , 

similar to the string gadget. It's not covered specifically in the (__J 

programs in this book. 

Proportional gadget. The proportional gadget plays the 
role of a knob or variable slide control, and lets a user set a 
variable's value by manipulating the gadget's control knob 
with the mouse. 

Proportional gadgets can have either vertical or horizontal 
slider bars, or a combination of both. The value represented 
by the position of the proportional gadget can be read by the 
application program. This, in turn, allows the program to set 
the position of the slider bar. Proportional gadgets are often 
used with windows in which only a portion of some available 
information is displayed. The slider bar is used to scroll, or 
otherwise move around, the larger information base and select 
a portion to appear in the window. 

Proportional gadgets also have a mode in which they're 
appropriately resized and repositioned when the window size 
is changed by the user. 

The GADGET Structure 

Table 19-1 shows the Intuition GADGET structure, its field 

names, and their numerical equivalents. It's similar, in some 

respects, to the MENU structure. A NEXT field points to the 

next GADGET structure for the window. It also contains i" i 

LEFTEDGE, TOPEDGE, WIDTH, and HEIGHT fields for po- LJ 

sitioning the gadget within the window. There are fields for 

pointers to an INTUITEXT structure (if there is text in the gad- f j 

get), the unselected (off) imagery (a BORDER structure or an LJ 

IMAGE structure), and the gadget's selected (on) imagery. If 

the gadget is a string or proportional gadget, the i j 

SPECIALINFO field contains the address of a STRINGINFO I I 

structure or PROPINFO structure, as well (see below). 

U 
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Table 19-1. Intuition GADGET structure 




Symbol: 


GADG 








Size: 44 


Bytes ($2C) 






n 


Field Size Name 


Offset 


Description 


Long 


GADG.NEXTGADGET 





Pointer to next GAD- 










GET structure 


n 


Word 


GADG.LEFTEDGE 


4 


Number of pixels from 








left edge 




Word 


GADG.TOPEDGE 


6 


Number of pixels from 
top edge 




Word 


GADG.WIDTH 


8 


Number of pixels wide 




Word 


GADG.HEIGHT 


10 


Number of pixels high 




Word 


GADG.FLAGS 


12 


Highlighting and ren- 
dering flags 




Word 


GADG.ACTIVATION 


14 


Event communication 
flags 




Word 


GADG.TYPE 


16 


Boolean, string, prop, 
or integer 




Long 


GADG.RENDER 


18 


Pointer to custom im- 
age or border 




Long 


GADG.SELECTRENDER 


22 


Pointer to custom se- 
lect image/border 




Long 


GADG.GADGETTEXT 


26 


Pointer to INTUITEXT 
for gadget 




Long 


GADG.MUTUALEXCLUDE 


1 30 


Mutual excludes for 
gadget activation 




Long 


GADG.SPECIALINFO 


34 


Pointer to special 
information 




Word 


GADG.GADGETID 


38 


User-definable data 
word 




Long 


GADG.USERDATA 


40 


Pointer to user- 
definable data area 



One gadget may need GADGET, INTUITEXT, IMAGE, 
BORDER, STRINGINFO and/or PROPINFO structures, all 
properly filled and linked by pointers. Like menus, this com- 
plexity can make programming with gadgets very tedious if 
the structure declarations are all in the source code. 

It would be handy to have a routine that automatically 
builds a Boolean gadget with a line border, given only a la- 
beled, null-terminated text string. For string and proportional 
gadgets, it would be handy to have routines that create and 
link all the necessary structures. 

Later in this chapter, these utility routines will be 
introduced. 
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Gadget FLAGS. The individual bits of the FLAGS field in 
the GADGET structure, control its highlighting and position. 
Table 19-2 lists the names of these flags, their hexadecimal 
values, and functional descriptions. 

Table 19-2. Gadget FLAGS 

Description 

Complements gadget when 

activated 

Draws box around gadget when 

activated 

Draws select render gadget image 

when activated 

No highlighting of activated gadget 

Set if gadget is image, clear if 

border 

Makes gadget top edge relative to 

window bottom 

Makes gadget left edge relative to 

window right 

Makes gadget width relative to 

window width 

Makes gadget height relative to 

window height 

Turns gadget on when it first 

appears 

Disables gadget selection 

Gadget ACTIVATION flags. The bits of the field in the 
GADGET structure provide for fine control of the user's inter- 
action with a gadget. Table 19-3 lists the names, values, and 
descriptions of the gadget ACTIVATION flags. 

Table 19-3. Gadget ACTIVATION Flags 



Name 


Bit Value 


GADGHCOMP 


0000 


GADGHBOX 


0001 


GADGHIMAGE 


0002 


GADGHNONE 


0003 


GADGIMAGE 


0004 


GRELBOTTOM 


0008 


GRELRIGHT 


0010 


GRELWIDTH 


0020 


GRELHEIGHT 


0040 


SELECTED 


0080 


GADGDISABLED 


0100 



Name 


Bit Value 


Description 


RELVERIFY 


0001 


Verifies that pointer was over gad- 
get when button was released 


GADGIMMEDIATE 


0002 


Sends gadget activated message to 
IDCMP 


ENDGADGET 


0004 


Used in requester-based gadgets to 
end requester 


FOLLOWMOUSE 


0008 


Gets continuous mouse position 
messages 


RIGHTBORDER 


0010 


Adjusts size of windows right bor- 
der to accommodate your gadget 



u 
u 
u 
u 
u 
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Name 


Bit Value 


Description 


LEFTBORDER 


0020 


Adjusts size of windows left bor- 


TOPBORDER 


0040 


der to accommodate your gadget 
Adjusts size of windows top bor- 


BOTTOMBORDER 


0080 


der to accommodate your gadget 
Adjusts size of windows bottom 
border to accommodate your 


TOGGLESELECT 


0100 


gadget 

Sets gadget to on/off with 

successive clicks 


STRINGCENTER 


0200 


Centers a string gadget in its 


STRINGRIGHT 
LONGINT 


0400 
0800 


region 

Right justifies a string gadget 
Permits entry of a long integer into 


ALTKEYMAP 


1000 


a string 

String uses an alternate Amiga 

keymap 



This chapter provides a set of support-code subroutines 
and macros to simplify gadget programming. This utility is 
named GADGETS.ASM. It can be found in Listing 19-1. Like 
the include files introduced in the previous chapters, use 
EMACS or your favorite text editor to type in the file and save 
it with the following name on your DEV disk: 

DEV:RAMIT/INCLUDES/GADGETS.ASM 

Listing 19-1. GADGETS.ASM 

Support subroutines and macros for gadget programming. 

.******************************** GADGETS.ASM BY DANIEL WOLF 

;COPYRIGHT 1987 BY COMPUTE! BOOKS 

,•33/21/87 

;GADGET SUPPORT ROUTINES FOR BOOLEAN, STRING, AND PROPORTIONAL TYPES 

SIZE.BBORDER EQU 40 .-SPECIFIC SIZE OF A 4-POINT BORDER W/COORDS 

BB.BUTTONLINES EQU 16 ;#BYTES FOR 4 POINT PAIRS 

JNEWPGADG MACRO 

NEWSGADG MACRO 
LEA \1,A0 
LEA \2,A1 
MOVE.W #\3,D4 
MOVE.W #\4,D5 
BSR MAKEASTRINGADGET 
MOVE.L \5,A0 
MOVE.L D0.A1 
BSR ADDNEWGADG 
ENDM 

NEWBGADG MACRO 
LEA \1,A1 
MOVE.W #\2,D4 
MOVE.W #\3,D5 
BSR MAKEAGADGET 
MOVE.L \4,A0 
MOVE.L D0.A1 
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BSR ADDNEWGADG 
ENDM 

ADDNEWGADG 
ZERO D0 
MOVE.W #-l,D0 
INTLIB ADDGADGET 
MOVE.L _THISGADGET, D0 
RTS 



MAKEAGADGET 



[SUBROUTINE ENTER WITH D4=LEPT,DS=TOP,D6=WID,D7=HEIGHT 
Al=POINTER TO GADGET TEXT 



MOVE.L A1,_THISGTEXT 

REMEMBERPUBMEM REMEMBERKEY, #SIZE.BBORDER 

TST.L D0 

BEQ ERR_MAKEAGADGETMEM 

MOVE.L D0,_THISBBORDER 

REMEMBERPUBMEM REMEMBERKEY, #SIZE. IT 

TST.L D0 

BEQ ERR_MAKEAGADGETMEM 

MOVE.L D0,_THISGITEXT 

MOVE.L D0.A0 

MOVE.L _THISGTEXT,A1 

BSR CREATETEXT 

INTLIB INTUITEXTLENGTH 

MOVEA.L _THISBBORDER,A0 

ADDA.L #SIZE.BORD,A0 

ADDI.W #4,D0 

BCLR.L #0,D0 

MOVE.W D0,4(A0) 

MOVE.W D0,8(A0) 

MOVE.W D0.D6 

MOVE.W _THISFONTHITE,D7 

ADDI.W #4,D7 

BCLR.L #0,D7 

MOVE.W D7,10(A0) 

MOVE.W D7,14(A0) 

MOVE.W #-l,D0 

CMP.W #STRGADGET,_THISGTYPE 

BNE.S BORDERMINONE 

MOVE.W #-5,D0 
BORDERMINONE 

MOVE.W D0,2(A0) 

MOVE.W D0,6(A0) 

MOVE.W D0,18(A0) 

MOVE.W D0,(A0) 

MOVE.W D0,12(A0) 

MOVE.W D0,16(A0) 

MOVEA.L _THISBBORDER,Al 

MOVE.L A0,BORD.XY(A1) 

MOVE.B #JAMl,BORD.DRAWMODE(Al) 

MOVE.B #l,BORD.FRONTPEN(Al) 

MOVE.B #5,BORD.COUNT(Al) 
_JUSTTHEGADGET 
-REMEMBERCHIPMEM REMEMBERKEY, ISIZE.GADG 

TST.L D0 

BEQ ERR_MAKEAGADGETMEM 

MOVE.L D0, THISGADGET 

MOVE.L D0.A0 

MOVE.W D4,GADG.LEPTEDGE(A0) 

MOVE.W D5,GADG.TOPEDGE(A0) 

MOVE.W D6,GADG.WIDTH(A0) 

MOVE.W D7.GADG. HEIGHT (A0) 

MOVE.W _THISGTYPE,GADG.TYPE(A0) 

MOVE.W _THISGACTIV,GADG.ACTIVATION(A0) 

MOVE.L _THISGITEXT,GADG.TEXT(A0) 

MOVE.W _THISGFLAGS,GADG. FLAGS (A0) 

MOVE . L _THISBBORDER,GADG . RENDER! A0 ) 

ZERO Dl 

MOVE.L _THISGADGET,D0 

RTS 



ERR_MAKEAGADGETMEM 
MOVE.L #CANTALLOCMEM,Dl 
ZERO D0 
RTS 



.•ALLOCATE ENOUGH FOR A BORDER STRUCT 
; WHICH INCLUDES 4 COORDINATES 



;JUST SAVE THE POINTER FOR NOW 

; REMEMBER MEM FOR INTUITEXT STRUCT 



A0=POINTER TO ALLOCATED ITEXT MEM 
AI=POINTER TO NULL-TERMINATED TEXT 
NOW SETUP THE INTUITEXT STRUCT 

USE LENGTH AND HEIGHT TO SET 

ADD 16 TO GET TO THE BORDER COORDS 



;THE BORDER COORDINATES 



,-ADD SOME ROOM TO THE BORDER, 

; ENOUGH FOR 2 PIXELS ABOVE AND BELOW 

;MAKE IT AN EVEN NUMBER 

•THE TEXT IN THE GADGET 

;AND ADD OTHER COORDS IN THE BORDER 



u 
u 
u 

u 

D 



NOW FILL OUT THE BORDER STRUCT 



REMEMBER MEM FOR GADGET STRUCT 



HANG ON TO THIS POINTER 
POINTER TO THIS GADGET IN A0 



NOW FILL UP THE GADGET STRUCTURE 
SET THE GADGET TYPE PRIOR TO ENTRY 
SET THE ACTIVATION FLAGS 
POINTER TO INTUITEXT FOR GADGET 
SET FLAGS PRIOR TO ENTRY 
CORRECT LATER IF PROP GADGET 
NO ERROR, GADGET PTR IN D0 



Li 
u 
u 



;MOVE ERROR CODE TO Dl 
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ERR_MAKEAGADGET 
MOVE.L ICANTALLOCMEM, Dl 
ZERO D0 
RTS 



;MOVE ERROR CODE TO Dl (UPICKIT) 



MAKEASTRINGADGET 
MOVE.W #STRGADGET; THISGTYPE 
MOVE.L A0,_THISGBUFFER 
MOVE.L Al,_THISGUNDOBUF 
REMEMBERPUBMEM REMEMBERKEY, #SIZE. SI 
TST.L D0 

BEQ ERR_MAKEAGADGETMEM 
MOVE.L D0.A0 

MOVE.L D0,_THISGSTRINGINFO 
MOVE.L _THISGBUFFER, SI. BUFFER) A0) 
MOVE.L _THISGUNDOBUF,SI.UNDOBUFFER(A0) 
MOVE.W «1,SI.BUFFERPOS(A0) 
MOVE.W #80,SI.MAXCHARS(A0) 
LEA SIZESTRING.A1 
BSR MAKEAGADGET 

MOVE.L _THISGSTRINGINFO,GADG.SPECIALINFO(A0) 

MOVE.W #BOOLGADGET,_THISGTYPE ; RESET DEFAULT BOOLEAN TYPE 

RTS 



; STRING GADGET ROUTINE 



;PTR TO NULL-TERMINATED STRING 
,PTR TO A UNIVERSAL UNDO BUFFER 



;NOW FILL IN THE STRINGINFO 



;USE THE SIZING STRING BELOW 



MAKEAPROPGADGET 

MOVE.W SPROPGADGET, THISGTYPE 

REMEMBERCHIPMEM REMEMBERKEY,#SIZE.IMAG 

TST.L D0 

BEQ ERR MAKEAGADGETMEM 

MOVE.L D0, THISGIMAGE 

REMEMBERCHIPMEM REMEMBERKEY, #SIZE . PI 

TST.L D0 

BEQ ERR MAKEAGADGETMEM 

MOVE.L D0.A0 

MOVE.L D0,_THISGPROPINFO 

MOVE.W tAUTOKNOBlFREEHORIZ, PI. FLAGS (A0) 

CMP.B #'V',D3 

BNE.S ITSHORIZONTAL 

MOVE.W #S8000,PI.VERTPOT(A0) 

MOVE.W #51000, PI. VERTBODY(A0) 

MOVE . W * AUTOKNOB 1 FREEVERT , PI . FLAGS ( A0 ) 
ITSHORIZONTAL 

MOVE.W #S8000,PI.HORIZPOT(A0) 

MOVE.W #81000, PI. HORIZBODY(A0) 

BSR _JUSTTHEGADGET 
MOVE.L _THISGADGET,D0 
ZERO Dl 

MOVE.L _THISGIMAGE,GADG.RENDER(A0) 
MOVE.L f0,GADG.TEXT(A0) 

MOVE.L THISGPROPINFO,GADG.SPECIALINFO(A0) 
ENDMAKEPROPGADG 
MOVE.W #BOOLGADGET,_THISGTYPE 
RTS 



[ PROPORTIONAL GADGET ROUTINE 

[ALLOCATE A IMAGE STRUCTURE 
[THIS IS A NECESSARY FORMALITY 
I EVEN WITH THE AUTOKNOB 1 1 1 1 1 1 It 

[ALLOCATE A PROPINFO STRUCTURE 



;NOW FILL IN THE PROPINFO 

[DEFAULT IS HORIZONTAL 

[SET BY CALLING PROGRAM FOR VERT 

[HALF MAX (MIDDLE OF RANGE) 

[THIN BODY (1000/FFFF = 1/16) 

[IF V PARAMETER, SET FREEVERT FLAG 

[HALF MAX (MIDDLE OF RANGE) 
[THIN BODY (ABOUT 1/16) 

[NOW THE GADGET STRUCTURE 



[AND LINK TO THE PROPINFO 
[YOU CAN CONTROL SIZE, ETC. 



[RESET BOOLEAN DEFAULT TYPE 



[STORAGE FOR POINTER TO GADGET 



JTHISGADGET 

DC.L 
JTHISGACTIV 

DC.W STRINGCENTERIRELVERIFYIGADGIMMEDIATE 

[LET US KNOW IF GADGET HIT1 
JTHISGFLAGS 

DC.W GADGHCOMP 
JTHISGTYPE 
- DC.W BOOLGADGET 

THISGTEXT 
~DC.L 

THISGITEXT 
- DC.L 

THISBBORDER 

DC.L 
SIZESTRING 

DC.B ' 

EVENPC 



JTHISGSTRINGINFO 

DC.L 
JTHISGBUFFER 

DC.L 



[HIGHLIGHT BY COMPLEMENTING 
[ITS BOOLEAN TYPE (SWITCH) 
[TEXT POINTER FOR GADGET 
[POINTER TO INTUITEXT FOR GADGET 
[POINTER TO BORDER FOR GADGET 
',0|BLANK SIZING STRING 

[POINTER TO STRINGINFO STRUCTURE FOR STRING GADGET 
(TEXT BUFFER FOR STRING GADGET 
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THISGUNDOBUF ;UNIVERSAL UNDO-BUFFER FOR ALL STRING GADGETS IN WINDOW 
"DC.L 

JTHISGIMAGE ; POINTER TO IMAGE FOR GADGET (MUST BE HERE, NOT USED I ) 

DC.L 

JTHISGPROPINFO ; POINTER TO PROPINFO STRUCTURE FOR PROP GADGET 

DC.L 

BUTTONBORDER ; SAMPLE OF THE BORDER STRUCTURE 

'DC.W ;LEFTEDGE JUST OUTSIDE GADGET 

DC.W ;TOPEDGE JUST OUTSIDE GADGET 

DC.B 1 ;FRONTPEN 

DC.B ;BACKPEN 

DC.B JAM1 ;DRAWMODE 

DC.B 5 ;# OF POINTS IN COORDINATE LIST 

DC.L _BUTTONLINES ; POINTER TO COORDINATE LIST 

DC.L .-NEXT BORDER 

BUTTONLINES 
"DC.W 0,-1,20,-1,20,10,0,10,0,-1 ;X0,Y0 XI, VI X2,Y2 X3.Y3 



u 
u 



u 
u 



Boolean Gadgets 

The MAKEAGADGET routine in GADGETS.ASM helps create 
Boolean gadgets for your windows. The calling program only 
provides text for the gadgets. MAKEAGADGET first allocates 
a BORDER structure and an INTUITEXT structure for the text 
imagery used in the gadget. An arithmetic section uses the 
current font height and a call to INTUITEXTLENGTH to get 
size data for the gadget, and then creates a list of border co- 
ordinates for the BORDER structure. Finally, a GADGET struc- 
ture is allocated and filled with appropriate default values. 
Those defaults for the Boolean gadgets are: 

GADGHCOMP Mode for gadget highlighting 
BOOLGADGET Type for the gadget 
TOGGLESELECT Mode for gadget activation 

Pointer fields are filled with addresses of the INTUITEXT 
and BORDER structures. 

Once the Boolean gadget has been created (using the sup- 
plied text) two additional calls are required to make it visible 
and usable. J I 

• First, a call to ADDGADGET (INTLIB ADDGADGET) is 
made to place the GADGET structure on a list of GADGET 
structures for this window. The call to ADDGADGET sped- [ | 
fies — 1 as the list position to insure that the gadget is added 

to the top of the list. 

• Then, once all gadgets have been made and added to the list, | ! 
a call is made to REFRESHGADGETS. All the gadgets will 

appear and become usable at once. 
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The programs accompanying this section are called 
BOOLGADGET1 and BOOLGADGET2 (Listings 19-2 and 19- 
3). They show how to use MAKEAGADGET to create a Bool- 
ean gadget with the text PRESS HERE. In the program, when 
the user selects the gadget, the program ends. When you ex- 
amine these listings, note how IDCMPFLAGS and IDCMP 
messages are used to assure the programs can detect user- 
interaction with the gadget. 

Listing 19-2. BOOLGADGET1.ASM 

Boolean gadget demonstration using support code routines. 



##;BOOLGADGET1.ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 

709/10/87 

BRA _START 

DOS EQU 1 
INT EQU 1 

WIN EQU 1 
GAD EQU 1 
TXT EQU 1 



INCLUDE "HEADER" 

MAIN 

TST.L ENDFROMWB 

BNE.S _BUILDAWINDOW 
FROHUSER 

DOSPRINT STDOUT,#MYMESSAGE 

ZERO D0 

MOVEA.L COMMAND, A0 

CMPI.B #'? , ,(A0) 

BNE.S _BUILDAWINDOW 

BRA USAGE 



;IF INITIATED FROM WB, THEN NO ANNOUNCEMENTS YET1 



lIF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 



;PUT ADDRESS OF COMMAND LINE IN A0 
;IF FIRST CHARACTER IS 7 THEN 



BUILDAWINDOW 
~MAKEWIN #MYWINDOWTITLE, 40 , 15 , 500 , 160 , ERROR 
MOVE.L D0, WINDOW ; WINDOW OPENED HAS ITS POINTER IN D0 



_BUILDAGADGET 
LEA MYGADGETEXT.A1 
MOVE.W #20, D4 
MOVE.W #20, D5 
BSR MAKEAGADGET 
MOVE.L WINDOW, A0 
MOVE.L _THISGADGET,A1 
MOVE.L A1,_FIRSTGADGET 
ZERO D0 
MOVE.W t-l,D0 
INTLIB ADDGADGET 

MOVE.L FIRSTGADGET,A0 
MOVE.L WINDOW, Al 
INTLIB REFRESHGADGETS 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S RELOOP 
MOVE.L D0.A1 



,-LEFTEDGE FOR GADGET 

;TOPEDGE FOR GADGET 

jMAKE THE GADGET, INTUITEXT, AND BORDER 

; ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
;ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 

;THIS ASSURES ITS AT THE TOP OF THE LIST 
; ATTACH GADGET TO WINDOW STRUCTURE 

;PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 

; NOW MAKE THE GADGET APPEARI 



; LISTEN TO PORT ATTACHED TO THIS WINDOW 
(WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



; MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 
.•POINTER TO INTUIMESSAGE COMES BACK IN D0 
;NO MESSAGE THERE, SO LOOP 
; POINTER TO INTUIMESSAGE CAME BACK. USE IN Al 
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MOVE.L IM. CLASS (A1),D2 ;CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

MOVE.W IM.C0DE(A1),D3 ;MENU AND HENUITEM APPEAR HERE 

HOVE.W IM.QUALIFIER(A1),D4 jKBYS APPEAR HERB 

SYSLIB REPLYHSQ ; QUICK, SEND MESSAGE BACK NOWI 

CMP.L tCLOSEWINDOW,D2 

BEO DONE ;IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO... 

CMP. I, #GADGETUP,D2 

BNE RELOOP fTHIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 

BSR DOGADGET 

RELOOP 
BRA LOOP 

DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1? 

PULLREG D0 
QUITNOW 

RTS 

ERROR 

DOSPRINT STDOUT,#ERRORTEXT 
MOVEQ *21,D0 
RTS 
USAGE 
DOSPRINT STDOUT, #USAGETEXT 
BRA DONE 

DOGADGET ;THIS CODE GETS EXECUTED IF GADGET USED 

RT8 

MYWINDOWTITLE 

DC.B ' BoolGadgetl by D. Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage t BoolGadgetl' ,10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MYMESSAGE 

DC.B 10, 'BoolGadgetl by-D. Wolf Copyright 1987 by Computet Publications' ,10, 

EVENPC 

WINDOW DC.L 

RP DC.L 

_FIRSTGADGET DC.L 

JTHISFONTHITE DC.W 9 ; DEFAULT FONT HEIGHT 

MYGADGETEXT ; GADGET NULL-TERMIHATED TEXT 

DC.B ' PRESS HEREI ' ,0 
EVENPC 
END 



Li 



The MAKEBGADG macro is illustrated in BOOLGADGET2. I j 
Once again, this macro's purpose is to make the use of the 
MAKEAGADGET subroutine simpler. 

U 

u 
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Listing 19-3. B00LGADGET2.ASM 

Boolean gadget demonstration using support code macros. 

##;300LGADGET2.ASM UY OAHIEL WOLF 
;COPYlUGHT 1987 !SY COMPUTE! PUBLICATIONS 
;39/10/B7 

BRA _START 

DOS EQU 1 
INT EOU I 
GFX EQU 1 

WIN EQU I 
TXT SQU 1 
GAD EQU 1 
DTIME EQU 100 

INCLUDE "HEADER" 



MAIN 

TST.L ENDFROMWB 

BNE.S _BUILDAWINDOW 
FROMUSER 

DOSPRINT STDOUT, #MYMESSAGE 

ZERO D0 

MOVEA.L COMMAND, A0 

CMPI.B #'?' ,(A0) 

BNE.S _BUILDAWINDOW 

BRA USAGE 



;IF INITIATED FROM WB, THEN NO ANNOUNCEMENTS YET! 
; THERE'S NO CONSOLE TO PRINT TO ! ! 1 



;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 



;PUT ADDRESS OF COMMAND LINE IN A0 
;IF FIRST CHARACTER IS ? THEN 



; PRINT USAGE INFORMATION TO USER CLI WINDOW 



BUILDAWINDOW 
"MAKEWIN #MYWINDOWTITLE,40,15,500,160,ERROR 



MOVE.L D0, WINDOW 

MOVE.L D0.A0 

MOVE.L WW.RPORT(A0),RP 



; WINDOW OPENED HAS ITS POINTER IN D3 
;FIND POINTER TO RASTPORT IN WINDOW STRUCTURE 
MAKEITEX GADGMESSAGE, ERROR, GMSG ;MAKE INTUITEXTS FOR THOSE WHICH WILL BE 
MAKEITEX GADGMESSAGE2, ERROR, GMSG2 ; REPEATED - THEN USE PRINTOLDAT1 1 i 



_BUILDAGADGET 

"LEA MYGADGETEXT.A1 

MOVE.W #20, D4 

MOVE.W #20, D5 

BSR MAKEAGADGET 

MOVE.L WINDOW, A0 

MOVE.L _THISGADGET,A1 

MOVE.L Al, FIRSTGADGET 

ZERO 00 

MOVE.W #-l,D0 

INTLIB ADDGADGET 

MOVE.L _FIRSTGADGET,A0 
MOVE.L WINDOW, Al 
INTLIB REFRESHGADGETS 



•LEFTEDGE FOR GADGET 

•TOPEDGE FOR GADGET 

;MAKE THE GADGET, INTUITEXT, AND BORDER 

.•ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
;ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 

STHIS ASSURES ITS AT THE TOP OF THE LIST 
; ATTACH GADGET TO WINDOW STRUCTURE 

;PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 

(NOW MAKE THE GADGET APPEAR! 



MOVE.L WINDOW, Al ;TURN GADGET OFF 

MOVE.L _FIRSTGADGET,A0 

ZERA A2 ;ITS NOT IN A REQUESTER, JUST A WINDOW 

INTLIB OFFGADGET 

PRINTNEWAT WINDOW, OFFMSG, 20, 40, DONE ,-PRINT A MESSAGE THAT ONLY APPEARS ONCE 



MOVE.L #DTIME,D1 
DOSLIB DELAY 



;WAIT 4 SECONDS 



SETAPEN RP,#0 

RECTFILL RP, #2, #10, #200, #35 ;BLANK OUT THE GADGET BEFORE 'ON' 

MOVE.L WINDOW, Al fTURN GADGET ON 
MOVE.L _FIRSTGADGET,A0 
ZERA A2 ;ITS NOT IN A REQUESTER 

INTLIB ONGADGET ;SINCE ONLY ONE GADGET, THIS WORKS TO MAKE IT 

; APPEAR - THIS ROUTINE CALLS 'REFRESHGADGETS' 
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PRINTNEWAT WINDOW, ONMSG, 20, 60, DONE ; PRINT A MESSAGE 

LOOP 
MOVE.L WINDOW, A0 

MOVE.L WW.USERPORT(A0) ,A0 .-LISTEN TO PORT ATTACHED TO THIS WINDOW 

SYSLIB WAITPORT jWAIT FOR A SPECIFIED MESSAGE TO ARRIVE 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 

SYSLIB GETMSG ; MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

TST.L D0 ;POINTER TO INTUIMESSAGE COMES BACK IN D0 

BEQ.S RELOOP ;NO MESSAGE THERE, SO LOOP 

MOVE.L D0.A1 (POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

MOVE.L IM. CLASS (A1),D2 ;CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

MOVE.W IM.CODE(Al) ,D3 (MENU AND MENUITEM APPEAR HERE 

MOVE.W IM.QUALIFIER(A1),D4 ;KEYS APPEAR HERE 

SYSLIB REPLYMSG ! QUICK, SEND MESSAGE BACK NOW1 

CMP.L #CLOSEWINDOW, D2 

BEQ DONE ;IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO... 

CMP.L #GADGETUP,D2 

BNE RELOOP ;THIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 

BSR DOGADGET 

RELOOP 
BRA LOOP 

DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ ;LOCAL LABEL 1$ VALID BETWEEN TWO NORMAL LABELS 

MOVE.L D0.A0 (I.E. BETWEEN QUIT AND QUtTNOW 

INTLIB CLOSEWINDOW 
1? 

PULLREG D0 
QUITNOW 

RTS 

ERROR 

DOSPRINT STDOUT, #ERRORTEXT 

MOVEQ #21, D0 

RTS 
USAGE 

DOSPRINT STDOUT, #USAGETEXT 

BRA DONE 

DOGADGET ;THIS CODE EXECUTED IF GADGET GETS CLICKED 

PUSHALL 

SETAPEN RP,#0 ;SET DRAWING PEN (FOREGROUND) = COL. REG. #0 

RECTFILL RP, #2, #100, #450, #120 ;BLANK OUT THE AREA WHERE MESSAGE WILL APPEAR 

MOVEA.L _FIRSTGADGET,A0 ;NOW CHECK IF GADGET TOGGLED ON OR OFF 

MOVE.W GADG. FLAGS (A0),D0 ;LOOK UP THE FLAGS SLOT OF GADGET STRUCTURE 

BTST.L #7,D0 ;IS THE GADGET 'SELECTED' ? (FLAG BIT = 1) 

BEQ.S CLRTXT ;NO , USE 'SELECT' MSG 

;YES, PRINT APPROPRIATE MESSAGE 

PRINTOLDAT WINDOW, GMSG , 20 , 100 , ERR_GAD 

; MOVE.L _FIRSTGADGET,A0 

(BCLR.W ¥7, GADG. FLAGS (A0) (DE-SELECT IT 

BRA ERR GAD 

(LEA GADGMESSAGE.Al ,-YES, USE 'DESELECT' MSG 

;BRA TEXTOUT 
CLRTXT 

PRINTOLDAT WINDOW, GMSG2 , 20 , 100 , ERR_GAD 

ZERO D0 

(LEA GADGMESSAGE2.A1 
(TEXTOUT 

(MOVEA.L WINDOW.A0 

(MOVE.L #20, D0 

(MOVE.L #100, Dl 

(BSR _PRINTTEXT (JUST FOR DEMONSTRATION, THIS ALLOCATES 

ERR GAD 

PULLALL (MEM EACH TIME, NOT GOOD 

RTS 



u 
u 
u 
u 
u 
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.**..* TEXT D ATA DECLARATIONS ***** 

MYWINDOWTITLE 

DC.B ■ BoolGadget2 by D. Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage: BoolGadget2 ' , 10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MYMESSAGE 

DC.B 10 , ' BoolGadget2 by D. Wolf Copyright 1987 by Computet Publications' ,10,0 

EVENPC 
GADGMESSAGE2 

DC.B ' Now press it again to SELECT ... ',0 

EVENPC 
GADGMESSAGE 

DC.B ' and again to DE-SELECT. ',0 

EVENPC 
OFFMSG 

DC.B 'OFFGADGET disables and ghosts the Gadget' ,0 

EVENPC 
ONMSG 

DC.B 'ONGADGET enables the Gadget ',0 

EVENPC 
MYGADGETEXT ;GADGET NULL-TERMINATED TEXT 

DC.B ' PRESS HEREI ',0 

EVENPC 

WINDOW DC.L ; POINTER TO WINDOW STRUCTURE 

RP DC.L .-POINTER TO WINDOW'S RASTPORT STRUCTURE 

_FIRSTGADGET DC.L ;POINTER TO GADGET'S STRUCTURE IN MEMORY 

_THISFONTHITE DC.W 9 J DEFAULT FONT HEIGHT 
GMSG DC.L (POINTER TO INTUITEXT STRUCTURE 

GMSG2 DC.L ; POINTER TO INTUITEXT STRUCTURE 
END 

String Gadgets 

String gadgets allow manipulation of a string of text charac- 
ters. In addition to the other structures needed for a Boolean 
gadget, a STRINGINFO structure is allocated and linked to the 
GADG.SPECIALINFO field of the GADGET structure. The 
MAKEASTRINGADGET subroutine uses a call to the 
MAKEAGADGET subroutine and some additional code to pre- 
pare a complete string gadget with minimum programming 
overhead. Default values used by the subroutine are easily 
customized to your unique needs. 

Prior to calling MAKEASTRINGADGET, the program 
source code should provide a text string buffer and an undo 
buffer, which maintains a backup of the text string for the user. 
An interesting feature of the undo buffer is that only one is 
needed for all the string gadgets used. There is no need to de- 
clare multiple undo buffers. The MAKEASTRINGADGET re- 
uses a single undo buffer. 
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The STRINGINFO Structure 

Table 19-4 shows the layout of a STRINGINFO structure, with 
field names and their numerical equivalents. 

This special gadget substructure has fields for pointers to 
the actual text string buffer and the undo buffer, and also 
specifies the starting character for displaying the string, maxi- 
mum number of characters for the string, and so on. The 
MAKEASTRINGADGET subroutine uses standard default val- 
ues, which display the string starting from its first character, 
and place the cursor at the first character in both the string 
and undo buffers. 

Table 19-4. Intuition STRINGINFO Structure for String Gadget 



Symbol: 


SI 






Size: 36 


bytes ($24 bytes) 






Field Size Name 


Offset Description 


Long 


SI.BUFFER 





Pointer to buffer for string 
gadget 


Long 


SI.UNDOBUFFER 


4 


Pointer to undo buffer for 
string gadget 


Word 


SI.BUFFERPOS 


8 


Position of cursor within 
buffer 


Word 


SI.MAXCHARS 


10 


Maximum number of char- 
acters in buffer 


Word 


SI.DISPPOS 


12 


First displayed character 
buffer position 


Word 


SI.UNDOPOS 


14 


Position of cursor within 
undo buffer 


Word 


SI.NUMCHARS 


16 


Number of characters cur- 
rently in buffer 


Word 


SI.DISPCOUNT 


18 


Number of characters visible 
in string gadget box 


Word 


SI.CLEFT 


20 


Number of pixels from left 
edge 


Word 


SI.CTOP 


22 


Number of pixels from top 
edge 


Long 


SI.LAYERPTR 


24 


Pointer to rastport holding 
gadget 


Long 


SI.LONGINT 


28 


User's typed-in integer value 


Long 


SI.KEYMAP 


32 


Pointer to alternate string 
gadget keymap 



u 
u 
u 
u 
u 



u 
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j J As was done for the Boolean gadget, a border is drawn for 

the string gadget. The sizing information for this border is de- 
p— rived from SIZESTRING, a string variable declared in the 
I ] GADGETS. ASM file (look for it toward the end of Listing 19- 
1). The border forms a box of a fixed size. You can alter the 

nsize of the box, but the default provides for equal-sized boxes 
I for all text strings in a window. 

One way to make the box smaller is to insert a some- 
where inside the SIZESTRING (between the opening and clos- 
ing quote). That has the effect of terminating the string with a 
shorter length because the is detected as the end of the 
SIZESTRING. 

The SIZESTRING can be shorter than the actual text 
string buffer supplied as the starting value of the string. The 
string in the gadget scrolls when the cursor reaches an end of 
the string gadget's display box. It is wise to provide an 80- 
character string buffer, even if it requires padding the string 
with spaces at the end. Eighty characters is a typical line of 
text in many computer applications. 

Use the SIZESTRING to dictate the string gadget's size, 
since exact pixel size declarations sometimes cause part of the 
image to ghost. Ghosting is the term used when a region of text 
is covered with a mask of dots. This has the effect of making 
the text lighter and harder to read. It's used to dim nonenabled 
menu items, as well as the titles of all nonactive windows. 

Once the string gadget is created, it's added to the list of 
gadgets by calling ADDGADGET, and is made to appear by 
calling REFRESHGADGETS. A new feature of Workbench 1.2 
is an Intuition routine called ACTIVATEGADGET. A call to this 
r ^ routine activates a string gadget without a mouse click. The 
I cursor appears at the programmed position in a string gadget. 
STRGADGET.ASM, Listing 19-4, shows how to declare 
_,«. the null-terminated string and buffers, and then create and 
I j display a string gadget. Once again, note the IDCMPFLAGS 

and IDCMP messages sent if the user deselects the string gad- 
p— * get. The program code can look up the current contents of the 
I string gadget's buffer and take action according to the user's 
input. This program simply uses PRINTITEXT to print the 
_^ buffer each time the user alters it. 



! I 
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Listing 19-4. STRGADGET.ASM 

String gadget demonstration using support code. 



##; STRGADGET.ASM BY DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 

(09/10/87 

BRA _START 

GPX EQU 1 



WIN EQU 
GAD EQU 
TXT EQU 
WBC EQU 



; ASSURE SOMEWHERE TO PRINT MESSAGES 



INCLUDE "HEADER" 

MAIN 
DOSPRINT STDOUT,#MYMESSAGE 
ZERO D0 

MOVEA.L COMMAND, A0 
CMPI.B #'?',(A0) 
BNE.S _BUILDAWINDOW 
BRA USAGE 



; OUTPUT TITLE MESSAGE REGARDLESS 



;PUT ADDRESS OF COMMAND LINE IN A0 
;IF FIRST CHARACTER IS ? THEN 



BUILDAWINDOW 

MAKEWIN #MYWINDOWTITLE,40, 15, 500, 160, ERROR 

MOVE.L D0, WINDOW (WINDOW OPENED HAS ITS POINTER IN DO 

MOVE.L D0,A0 

MOVE.L WW.RPORT(A0),RP (FIND POINTER TO RASTPORT IN WINDOW STRUCTURE 



BUILDAGADGET 

LEA SGBUFFER.A0 

LEA SGUNDOBUFFER,Al 

MOVE.W #20, D4 

MOVE.W #20, D5 

BSR MAKEASTRINGADGET 

MOVE.L WINDOW, A0 

MOVE.L THISGADGET.A1 

MOVE.L A1,_FIRSTGADGET 

ZERO D0 

MOVE.W #-l,D0 

INTLIB ADDGADGET 

MOVE.L FIRSTGADGET.A0 
MOVE.L WINDOW, Al 
INTLIB REFRESHGADGETS 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S RELOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L tCLOSEWINDOW, D2 

BEQ DONE 

j CMP.L #GADGETUP,D2 

;BNE RELOOP 

BSR DOGADGET 

RELOOP 
BRA LOOP 



•LEFTEDGE FOR GADGET 

(TOPEDGE FOR GADGET 

(MAKE THE GADGET, INTUITEXT, AND BORDER 

; ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
;ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 

;THIS ASSURES ITS AT THE TOP OF THE LIST 
; ATTACH GADGET TO WINDOW STRUCTURE 

,-PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 

(NOW MAKE THE GADGET APPEAR1 



; LISTEN TO PORT ATTACHED TO THIS WINDOW 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



(MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

(POINTER TO INTUIMESSAGE COMES BACK IN D0 

(NO MESSAGE THERE, SO LOOP 

(POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

(CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

(MENU AND MENUITEM APPEAR HERE 

(KEYS APPEAR HERE 

(QUICK, SEND MESSAGE BACK NOW1 



(IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO... 
(THIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 



u 
u 
u 
u 
u 
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DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, 00 

BEQ.S 1$ 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1$ 

PULLRES D0 
QUITNOW 

RTS 

ERROR 
DOSPRINT STD0UT,#ERRORTEXT 
MOVEQ #CANTOPENWINDOW,D0 
RTS 

USAGE 
DOSPRINT STDOUT, #USAGETEXT 
BRA DONE 

DOGADGET ;THIS CODE EXECUTED IF GADGET TOGGLED 

PUSHALL 

SETAPEN RP,#0 (SET DRAWING PEN (FOREGROUND) = COL. REG. #0 

RECTFILL RP, #2, #100, #450, #120 ; BLANK OUT THE AREA WHERE MESSAGE WILL APPEAR 

; PRINT CONTENTS OF STRING GADGET BUFFER 
TEXTOUT 

PRINTNEWAT WINDOW ,'SGBUFFER, 20 , 100 , CLRTXT 

ZERO D0 
CLRTXT 

PULLALL 

RTS 

...... TEXT DATA DECLARATIONS ***** 

MYMESSAGE 

DC.B 10,' StrGadget by D. Wolf copyright 1987 by Compute! Publications ',10,0 

EVENPC 
MYWINDOWTITLE 

DC.B ' StrGadget by D. Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage i StrGadget ', 10 , 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
SGBUFFER 

DC.B 'CLICK HERE, PLAY, THEN PRESS RETURN', .-INITIAL STRING IN GADGET 

EVENPC 
SGUNDOBUFFER 

DCB.B 80,0 (UNIVERSAL STRING GADGET 'UNDO' BUFFER 

WINDOW DC.L (POINTER TO WINDOW STRUCTURE 

RP DC.L (POINTER TO WINDOW'S RASTPORT STRUCTURE 

_FIRSTGADGET DC.L (POINTER TO GADGET'S STRUCTURE IN MEMORY 

THISFONTHITE DC.W 9 (DEFAULT FONT HEIGHT 
"END 

Proportional Gadgets 

Proportional gadgets are the most complex gadgets to create 
and use. You can arrange them vertically, horizontally, or in 
combinations. You can also attach them to window borders as 
scroll bars. They provide a variable value to look up in the 
GADGET structure and use in the program. They are visually 
elegant and powerful for user interaction, which can obviate 
the need to type in a number. 
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The PROPINFO Structure 

Table 19-5 shows the PROPINFO STRUCTURE, which plays 
the role of SPECIALINFO in proportional gadget 
programming. 

The Proportional gadget needs a SPECIALINFO structure 
to provide all the additional parameters and data for a Propor- 
tional gadget. The PROPINFO STRUCTURE contains fields for 
special flag bits, 16-bit relative values of the gadget 
(PI.HORIZPOT or PI.VERTPOT), and a size and increment 
value (PI.HORIZBODY or PI.VERTBODY) for the slider knob. 
These values are read during the program to determine the 
current value of the proportional variable. 

Table 19-5. Intuition PROPINFO Structure for Proportional 
Gadget 

Symbol: PI 

Size: 22 bytes ($16 bytes) 

Field Size Name Offset Description 

Word PI.FLAGS Hag bits 

Word PI.HORIZPOT 2 Sixteen-bit fractional pot 

value 

Sixteen-bit fractional pot 
value 

Sixteen-bit fractional knob 
size 

Sixteen-bit fractional knob 
size 

Knob container width 
Knob container height 
Knob movement/value 
increment 

Knob movement/value 
increment 

Knob container left border 
Knob container top border 



Word 


PI.VERTPOT 


4 


Word 


PI.HORIZBODY 


6 


Word 


PI.VERTBODY 


8 


Word 
Word 
Word 


PI.CWIDTH 

PI.CHEIGHT 

PI.HPOTRES 


10 
12 
14 


Word 


PI.VPOTRES 


16 


Word 
Word 


PI.LEFTBORDER 
PI.TOPBORDER 


18 
20 
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The MAKEAPROPGADGET subroutine in GADGETS 
.ASM (Listing 19-1) provides a simple way to arrange all the 
bits and pieces of proportional gadgets. It uses the 
MAKEAGADGET subroutine, but also contains code for allo- 
cating and filling in the PROPINFO standard default values. 
The AUTOKNOB mode lets Intuition create the slider image. 
MAKEAPROPGADGET uses sizing data passed in registers to 
specify the length, height, and position of the proportional 
gadget region. 

Self-adjusting proportional gadgets. The GREL- 
BOTTOM, GRELRIGHT, GRELWIDTH, and GRELHEIGHT 
flags insure that the proportional gadget is positioned and 
sized correctly when the user resizes the window. This relative 
positioning is often used with scroll bars that remain attached 
to a window's border and adjust to window size changes. 
When the GRELBOTTOM flag is set, the relative position data 
passed to MAKEAPROPGADGET is a negative number. For 
instance, —10 causes the gadget to appear 10 pixels from the 
window's bottom border. If you want to have a scroll bar at 
the right edge of a window, 10 pixels wide and extending from 
the drag bar down to the sizing gadget, set the GRELRIGHT 
and GRELHEIGHT flags. In this example, set TOPEDGE = 10, 
LEFTEDGE = -10, WIDTH = 10 and HEIGHT 20. 

The listings provided with this section are 
PROPGADGET1.ASM and PROPGADGET2.ASM (Listings 
19-5 and 19-6). The first features a horizontal proportional 
gadget. The second features a proportional gadget positioned 
as a scroll bar inside the window using the GRELxaxt (for in- 
stance, GETRELWIDTH) flag bits from the GADGET structure. 
Notice that this gadget is moved and resized correctly over a 
wide range of window sizes. When the slider is moved, its 
value (in hexadecimal, between $0000 and $FFFF) is printed 
out in the CLI window. Again, note the use of IDCMP and the 
way the PROPINFO data are read by the program code. 
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Listing 19-5. PR0PGADGET1.ASM 

Proportional gadget using support routines. 

##(PROPGADGETl.ASM BY DANIEL WOLF 
[COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 
[09/10/87 

BRA _START 

Witt EQU 1 
GAD EQU 1 
TXT EQU 1 

MAT EQU 1 

HEX EQU 1 

WBC EQU 1 ; ASSURE WE HAVE STDOUT EVEN IP FROM WORKBENCH 

;WE CAN ALWAYS DOSPRINT MESSAGES THEN 

INCLUDE "HEADER" 

MAIN 
DOSPRINT STDOUT, #MYMESSAGE ;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 
ZERO D0 

MOVEA.L COMMAND, A0 [ PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'?\(A0) (IF FIRST CHARACTER IS ? THEN 

BNE.S _BUILDAWINDOW 
BRA USAGE 

_BUILDAWINDOW 
MAKEWIN #MYWINDOWTITLE , 40 , 15 , 500 , 160 , ERROR 

MOVE.L D0, WINDOW (WINDOW OPENED HAS ITS POINTER IN D0 

MOVE.L D0.A0 
MOVE.L WW.RPORT(A0),RP ;FIND POINTER TO RASTPORT IN WINDOW STRUCTURE 



_BUILDAGADGET 
MOVE.W #20, M 
MOVE.W #120, D5 
MOVE.W #100,D6 
MOVE.W #15, D7 
BSR MAKEAPROPGADGET 

MOVE.L WINDOW, A0 
MOVE.L _THISGADGET,A1 
MOVE.L A1,_FIRSTGADGET 
ZERO D0 
MOVE.W #-l,D0 
INTLIB ADDGADGET 

MOVE.L _FIRSTGADGET,A0 
MOVE.L WINDOW, Al 
INTLIB REFRESHGADGETS 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0) ,A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S RELOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE .W IM . CODE ( Al ) , D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

CMP.L #CLOSEWINDOW, D2 

BEQ DONE ' 

CMP.L #GADGETUP,D2 

BNE RELOOP 

BSR DOGADGET 

RELOOP 

BRA LOOP 



; DEFAULT WILL BE A HORIZONTAL PROPORTIONAL GADGET 

■LEFTEDGE FOR GADGET 

(TOPEDGE FOR GADGET 

(WIDTH FOR GADGET 

(HEIGHT FOR GADGET 

(MAKE THE GADGET, INTUITEXT, AND BORDER 



(ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
(ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 



(THIS ASSURES ITS AT THE TOP OF THE LIST 
(ATTACH GADGET TO WINDOW STRUCTURE 



(PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 
(NOW MAKE THE GADGET APPEAR1 



(LISTEN TO PORT ATTACHED TO THIS WINDOW 
(WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



(MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

(POINTER TO INTUIMESSAGE COMES BACK IN D0 

(NO MESSAGE THERE, SO LOOP 

(POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

(CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

(MENU AND MENUITEM APPEAR HERE 

(KEYS APPEAR HERE 

(QUICK, SEND MESSAGE BACK NOW1 



(IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO. . 
[THIS ISN'T A CLOSE OR A MENUPICK, SO LOOP 
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DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1$ 

PULLREG D0 
QUITNOW 

RTS 

ERROR 

DOSPRINT STDOUT, #ERRORTEXT 

MOVEQ #21,D0 

RTS 
USAGE 

DOSPRINT STDOUT, #USAGETEXT 

BRA DONE 

DOGADGET ;THIS CODE EXECUTED IF GADGET TOGGLED 

PUSHALL 

MOVEA.L _FIRSTGADGET,A0 ;USE GADGET STRUCTURE TO 

MOVEA.L GADG.SPECIALINFO(A0),A0;FIND THE PROPINFO SUB-STRUCTURE POINTER 
ZERO D0 

MOVE.W PI.HORIZPOT(A0),D0 ;AND THE VALUE OF THE 'POT' VARIABLE 
BSR HEXCONVERT (NOW DECODE AND PRINT VALUE TO CLI WINDOW 

PULLALL 
RTS 

.**.** TEXT DATA DECLARATIONS ***** 

MYMESSAGE 

DC.B ' PropGadgetl by D. Wolf Copyright 1987 by Compute! Publications ',10, 

EVENPC 
MYWINDOWTITLE 

DC.B ' PropGadgetl by D. Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage: PropGadgetl' ,10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 

WINDOW DC.L [POINTER TO WINDOW STRUCTURE 

RP DC.L ; POINTER TO WINDOW'S RASTPORT STRUCTURE 

_FIRSTGADGET DC.L [POINTER TO GADGET'S STRUCTURE IN MEMORY 

_THISFONTHITE DC.W 9 [DEFAULT FONT HEIGHT 
END 

Listing 19-6. PROPGADGET2.ASM 

Proportional gadget scroll bar uses relative positioning within window. 

##;PROPGADGET2.ASM BY DANIEL WOLF 
[COPYRIGHT 1987 BY COMPUTE 1 PUBLICATIONS 
[09/10/87 

BRA _START 

MAT EQU 1 

GAD EQU 1 
TXT EQU 1 
HEX EQU 1 

WBC EQU 1 

INCLUDE "HEADER" 
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MAIN 
DOSPRINT STDOUT, #MYMESSAGE jIF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 
ZERO D0 

MOVEA.L COMMAND, A0 ;PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'?',(A0) ;IF FIRST CHARACTER IS ? THEN 

BNE.S _BUILDAWINDOW 
BRA USAGE 

_BUILDAWINDOW 
LEA NEWWINDOW.A0 
INTLIB OPENWINDOW 
TST.L D0 
BEQ ERROR 
MOVE.L D0, WINDOW 



;WINDOW OPENED HAS ITS POINTER IN D0 



u 
u 
u 
u 
u 



BUILDAGADGET 

MOVE.W #0,D4 

MOVE.W #-8,D5 

MOVE.W #-15, D6 

MOVE.W #8,D7 

BSR MAKEAPROPGADGET 

MOVEA.L WINDOW, A0 

MOVEA.L _THISGADGET,A1 

MOVE.L Al, FIRSTGADGET 



; DEFAULT WILL BE A HORIZONTAL PROPORTIONAL GADGET 
;LEFTEDGE FOR GADGET 
;TOPEDGE FOR GADGET (RELATIVE TO BOTTOM) 
.•RELATIVE WIDTH, 15 PIXELS LESS THAN WINDOW 

;MAKE THE GADGET, INTUITEXT, AND BORDER 

; ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
;ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 



_CHANGEGADGFLAGS 
MOVE.W GADG. FLAGS (A1),D0 
ORI.W SGRELWIDTHIGRELBOTTOM, 
MOVE . W D0 , GADG . FLAGS ( Al ) 



_NOWADDTHEGADGET 
"ZERO D0 

MOVE.W #-l,D0 

INTLIB ADDGADGET 

MOVE.L _FIRSTGADGET,A0 
MOVE.L WINDOW, Al 
INTLIB REFRESHGADGETS 



THERE'S HOW TO USE CUSTOM FLAGS COMBINATIONS 
;IN SPITE OF THE DEFAULT ' MAKEAGADGET ' FLAGS 
-SET THE RELATIVE WIDTH AND HEIGHT FLAGS 
;BRING FLAGS OUT, 'OR' AS DESIRED, PUT 'EM BACK 
;THIS COMBO WILL MAKE A SCROLL BAR 



;THIS ASSURES ITS AT THE TOP OF THE LIST 
;ATTACH GADGET TO WINDOW STRUCTURE'S GADGET LIST 



;PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 
,-NOW MAKE THE GADGET APPEAR! 



LOOP 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW. USERPORT ( A0 ) ,A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S RELOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 



CMP.L #CLOSEWINDOW, 
BEQ DONE 

CMP.L #GADGETUP,D2 
BNE TRYDOWN 
BSR DOGADGET 
TRYDOWN 
CMPI.L #GADGETDOWN, 
BNE RELOOP 
BSR DOGADGET 



D2 



[LISTEN TO PORT ATTACHED TO THIS WINDOW 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



jMESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

; POINTER TO INTUIMESSAGE COMES BACK IN D0 

;NO MESSAGE THERE, SO LOOP 

; POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

,- CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

;MENU AND MENUITEM APPEAR HERE 

;KEYS APPEAR HERE 

; QUICK, SEND MESSAGE BACK NOWl 



;IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO. 
;THIS ISN'T A CLOSE OR A GADGETUP 



f MAYBE ITS A GADGET DOWN MESSAGE 



RELOOP 
BRA LOOP 

DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S IS 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1? 

PULLREG D0 
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QUITNOW 
RTS 

ERROR 

DOSPRINT STDOUT,#ERRORTKXT 

MOVEO #CANTOPENWINDOW,D0 

RTS 
USAGE 

DOSPRINT STDOUT, #USAGETEXT 

BRA DONE 

DOGADGET jTHIS CODE EXECUTED IF GADGET TOGGLED 

PUSHALL 

MOVEA.L _PIRSTGADGET,A0 ;USE GADGET STRUCTURE TO 

MOVEA.L GADG.SPECIALINFO(A0),A0;FIND THE PROPINPO SUB-STRUCTURE POINTER 
ZERO D0 

MOVE.W PI.HORIZPOT(A0),D0 ;AND THE VALUE OF THE 'POT' VARIABLE 
BSR HEXCONVERT ;NOW DECODE AND PRINT VALUE TO CLI WINDOW 

PULLALL 
RTS 

,«**** TEXT DATA DECLARATIONS ***** 

MYHESSAGE 

DC.B ' PropGadget2 by D. Wolf Copyright 1987 by Compute! Publications ',10,0 

EVENPC 
MYWINDOWTITLE 

DC.B ' PropGadget2 by D. Wolf ',0 
. .EVENPC 
USAGETEXT 

DC.B ' Usage t PropGadget2 ' , 10 , 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 

WINDOW DC.L ; POINTER TO WINDOW STRUCTURE 

RP DC.L ; POINTER TO WINDOW'S RASTPORT STRUCTURE 

PIRSTGADGET DC.L ; POINTER TO GADGET'S STRUCTURE IN MEMORY 

JTHISFONTHITE DC.W 9 (DEFAULT FONT HEIGHT 

NEWWINDOW 
DC.W 100 
DC.W 20 
DC.W 500 
DC.W 160 
DC.B -1 
DC.B -1 

DC.L CLOSEWINDOW1GADGETUP 

DC . L WINDOWSIZING I WINDOWDRAG 1 WINDOWDEPTH I WINDOWCLOSE 1 SMART_REFRESH 
DC.L 
DC.L 

DC.L MYWINDOWTITLE 
DC.L 
DC.L 

DC.W 140 ;BE CAREFUL MIN HEIGHT AND WIDTH AREN'T 

DC.W 140 !SO SMALL THAT THE RELATIVE HEIGHT AND WIDTH 

DC.W 640 I OF THE GADGET CAN BECOME LESS THAN ZERO 

DC.W 400 ;OR YOU'LL BE SORRY1 (COULD ELIMINATE SIZING INSTEAD) 

DC.W WBENCHSCREEN 
END 

Programming with Gadgets 

Here are some important points to keep in mind when using 
gadgets: First, Gain as much experience as possible by experi- 
mentation. It's not possible to cover the enormous variety of 
combinations of flags, positioning options, and so on within 
this text. 
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Second, changing a gadget in use can be tricky. There are 
several routines in the Intuition library for this purpose. You 
may wish to make a gadget disappear, or change the character 
string used in a string gadget. Here are the functions: 

ADDGADGET Adds a gadget to the window's gadget list 

REMGADGET Removes a gadget from the window's gadget 

list 
MODIFYPROP Alters a proportional gadget in use 

REFRESHGADGETS Displays gadgets on the window's gadget list 

Each of these functions is called with a pointer to the rele- 
vant structure in register AO. To alter the features of a string or 
Boolean gadget, first remove it from the window's gadget list 
(REMGADGET). The program can then modify fields in the 
structures associated with that gadget. Next, a call to 
ADDGADGET and REFRESHGADGETS will redisplay it. 
ADDGADGET also requires a gadget list position, discussed 
earlier (see the initial paragraphs of the section on Boolean 
gadgets). 

The MODIFYPROP function changes flags, pot values, 
and body values without first removing and adding the gad- 
get. More information on the register data and calling se- 
quence for these routines is in the Amiga Intuition Reference 
Manual and the Intuition function call table. 
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CHAPTER 20 

Intuition Requesters 



After introducing windows, texts, menus, and gadgets, there's 
only one more major Intuition interactive resource: requesters. 
Most of what has been applied previously in the construction 
of INTUITEXT and GADGET structures also applies to re- 
questers. Requesters behave like windows, except the user 
must respond to them before continuing other work. 

Requesters are equipped with some type of close gadget to 
permit a message to reach the program to remove the requester 
and allow other work to continue. Just about anything you can 
do with a menu or gadget in a window is possible using a re- 
quester. The requester can't have a real menu, but it can have a 
variety of gadgets for user interactions. Requesters open in a 
window and are attached by the system to that window. There- 
fore, communication with a requester is handled by the Win- 
dow's I/O port using IDCMPFLAGS and INTUIMESSAGES. 

The Autorequester 

With such capabilities, most requesters need a great deal of 
preparation. The programmer may have to supply BORDER, 
GADGET, and INTUITEXT structures (perhaps several of 
each), appropriately linked. Naturally, there is a REQUESTER 
structure with many fields for pointers to these auxiliary struc- 
tures. The simplest type of requester, called the autorequester, 
uses a method that is simpler than filling in an entire RE- 
QUESTER structure. 

An autorequester presents a yes/no or continue choice to 
the user. A special Intuition call (AUTOREQUEST) is used to 
do most of the work of preparing this one- or two-choice 
requester. 

Programmers may want to use the autorequester most fre- 
quently as a warning to users when deleting data or opening a 
new file. It's common practice to alert a user to the possibility 
that data will be lost or damaged by user action, and permit 
the user to back up and safely move to another option. The 
autorequester is well suited to this warning function. 
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The REQUESTER Structure 

Table 20-1 has the definition of the REQUESTER structure. 
The structure fields include the usual positioning data 
(TOPEDGE, LEFTEDGE, and so on) and pointer fields that 
point to an existing list of gadgets, a list of borders, and a list 
of Intuitexts. The lists are actually lists of the structures, each 
with its own positioning and drawing specifications, and are 
linked by the NEXT field pointers in each. There is also a field 
for a pointer to a custom bitmap that can contain imagery for 
the requester. As with the other complex Intuition structures, 
the REQUESTER structure also contains a FLAGS field that 
controls some of its features. 



Table 20-1. Intuition Requester Structure 

Symbol: REQ Size: 112 bytes ($70 bytes) 
Field Size Name Offset 

Long REQ.OLDERREQUEST 



Word 


REQ.LEFTEDGE 


Word 


REQ.TOPEDGE 


Word 
Word 
Word 


REQ.WIDTH 

REQ.HEIGHT 

REQ.RELLEFT 


Word 


REQ.RELTOP 


Long 


REQ.GADGET 


Long 


REQ.BORDER 


Long 


REQ.TEXT 


Word 
Byte 


REQ.FLAGS 
REQ.BACKFILL 


Long 


REQ.LAYER 


Long 


REQ.IMAGEBMAP 



Description 

Pointer to older requester 
4 Number of pixels from 

left edge 
6 Number of pixels from 

top edge 
8 Number of pixels wide 

10 Number of pixels high 

12 Number of pixels from 
left relative to pointer 

14 Number of pixels from 
top relative to pointer 

16 Pointer to gadget list for 
requester 

20 Pointer to BORDER 
structure 

24 Pointer to INTUITEXT 
structure 

28 Hag bits 

30 Pen Number for back- 
plane fill 

32 Pointer to Lj^R struc- 
ture; 32 empty bytes of 
padding (not used by 
programs) 

68 Pointer to bitmap of 
predrawn image 



u 
u 
u 
u 
u 
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Field Size Name Offset Description 

Long REQ.RWINDOW 72 Pointer to window of this 

requester; 36 empty bytes 
of padding (not used by 
programs) 

Requirements of the Autorequester 

The autorequester is the simplest type of requester used by In- 
tuition. It's the easiest requester to program because an Intu- 
ition function (AUTOREQUEST) does almost all the work. 

When a simple warning or yes/no choice is required of a 
user, the autorequester is the recommended way to present it. 
The complete REQUESTER structure does not need to be filled 
in when creating an autorequester. The Intuition AUTO- 
REQUEST call does most of the work. The program simply 
provides three null-terminated text declarations: 

• A text string for the user's positive choice (yes) 

• A text string for the user's negative choice (no) 

• A text string describing the choice (danger, continue?) 

These are converted to Intuitext strings. The addresses of 
the three strings are passed to AUTOREQUEST. The 
AUTOREQUEST function is also supplied with positioning 
information for the requester. 

One more feature of the autorequester is that it creates a 
new set of IDCMPFLAGS. The programmer can select a com- 
bination of IDCMPFLAGS to indicate a positive reply by the 
user, and other flags for a negative reply. The AUTOREQUEST 
function puts them into effect automatically. They remain in 
effect as long as the autorequester is displayed. The previous 
IDCMPFLAGS are automatically restored when the autore- 
quester is finished with its work. 

The AUTOREQUEST function takes the positive and neg- 
ative INTUITEXT structures and makes them into gadgets. The 
positive gadget is placed in the lower left of the AUTO- 
REQUESTER and the negative gadget in the lower right. The 
Intuition system knows where the positive and negative gad- 
gets are, and can send messages to the program in data regis- 
ter DO, indicating which was selected by the user. (See Figure 
20-1.) 
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Figure 20-1. Autorequester 

Note that the autorequester is attached to the Intuition window. 
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SCREEN 



MINDOH 



Listing 20-1, REQS.ASM, is an include file with support 
subroutines and macros for the programs appearing later in 
this chapter. Enter the file and save it on the DEV disk with 
the name: 

DEV:RAMIT/INCLUDES/REQS.ASM 

Listing 20-1. REQS.ASM 

Autorequester support routines and macros. 



.•ft****************************** REQS . ASM by DANIEL WOLF 

; COPYRIGHT 1987 BY COMPUTE I BOOKS 

.-03/21/87 

fA MACRO TO CREATE REQUESTER INTUITEXTS FROM BODY, POS, AND NEG NTEXTS 

MAKEREQ MACRO .-WINDOW PTR, PTR TO BODY NTEXT, PTR TO POS, PTR TO NEG, ERROR 
; RESULT IS 3 INTUITEXT ADDRESSES IN A1,A2,A3 
LEA \1,A1 
ZERA A2 
IFNC '\2','0' 
LEA \2,A2 
ENDC 

LEA \3,A3 

BSR SETUPAUTOREQUEST 
TST.L D4 
BNE \4 
ENDM 

!A MACRO TO SAVE THE RESULTS OF MAKEREQ (3 INTUITEXTS COME BACK1) 

SAVEREQ MACRO ; LABEL OF HIDING PLACE WITH THREE LONG WORDS RESERVED 

PUSHREG A4 

LEA \1,A4 ;PUT LABEL INTO A4 

BSR _SAVEREQ 
PULLREG A4 
ENDM 



u 
u 
u 
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_SAVBREQ 
MOVE.L A1,(A4)+ 
MOVE.L A2,(A4)+ 
MOVE.L A3,(A4) 
RTS 

;A MACRO TO CREATE AND SHOW THE REQUESTER IN A GIVEN WINDOW W/ EXISTING 3 ITEXTS 

REQUEST MACRO ;WINDOW,PTR TO REQUESTER ITEXTS, REQXMAX, REQYMAX 
PUSHREG A0-A4/D2-D3 
MOVE.L \1,A0 

LEA \2,A4 ; BRING IN THREE ITEXT PTRS FROM HIDING 

IPC '\3', ' ' 

MOVE.L #REQXMAX,D2 ;WIDTH 
MOVE.L #REQYMAX,D3 ;HEIGHT 
ENDC 

BSR _REQUEST 
PULLREG A0-A4/D2-D3 
ENDM 

_REQUEST 
MOVE.L (A4) + ,A1 
MOVE.L (A4)+,A2 
MOVE.L (A4),A3 
ZERO D0 ;TOP 

ZERO Dl ;LEFT 

INTLIB AUTOREQUEST 
RTS 

;AUTOREQUEST SUPPORT ENTER W/ A0->WINDOW A1,A2, A3->BODY, POS, NEG TEXTS 

SETUPAUTOREQUEST ;SETS UP FOR USING AUTOREQUESTER 

MOVE.L A0,_THISREQWINDOW ; STASH POINTERS WHILE ALLOCATING 

MOVE.L A1,_THISREQBTEXT 
MOVE.L A2,_THISREQPTEXT 
MOVE.L A3,_THISREQNTEXT 

_BODREQALLOC 
REMEMBERPUBMEM REMEMBERKEY, #SIZE. IT {ALLOCATE FOR AN INTUITEXT 
TST.L D0 

BEQ ERR_MAKEAREQMEM 

MOVE.L D0,_THISREQBITEXT ;THIS IS THE BODY INTUITEXT 

MOVE.L D0.A0 
MOVE.L _THISREQBTEXT,A1 
BSR CREATETEXT 
ADD.W #10,IT.TOPEDGE(A0) 
ADD.W #10,IT.LEFTEDGE(A0) 

_POSREQALLOC 
MOVE.L #0,_THISREQPITEXT jPROVIDE FOR POSSIBILITY OF NO POSITIVE 

TST.L JTHISREQPTEXT 
BEQ.S _NEGREQALLOC 

REMEMBERPUBMEM REMEMBERKEY, #SIZE. IT ,-ALLOCATE FOR AN INTUITEXT 
TST.L D0 

BEQ ERR MAKEAREQMEM 

MOVE.L D0,_THISREQPITEXT [THIS IS POSITIVE INTUITEXT 

MOVE.L D0.A0 
MOVE.L THISREQPTEXT.A1 
BSR CREATETEXT 
ADDQ.W #1,IT.TOPEDGE(A0) 
ADDQ.W #4,IT.LEFTEDGE(A0) 

_NEGREQALLOC 
REMEMBERPUBMEM REMEMBERKEY, #SIZE. IT {ALLOCATE FOR AN INTUITEXT 
TST.L D0 

BEQ ERR_MAKEAREQMEM 

MOVE.L D0,_THISREQNITEXT iTHIS IS NEGATIVE INTUITEXT 

MOVE.L D0.A0 
MOVE.L _THISREQNTEXT,A1 
BSR CREATETEXT 
ADDQ.W #1,IT.TOPEDGE(A0) 
ADDQ.W #4,IT.LEFTEDGE(A0) 

MOVE.L _THISREQWINDOW,A0 
MOVE.L _THISREQBITEXT,A1 
MOVE.L _THISREQPITEXT,A2 
MOVE.L _THISREQNITEXT,A3 
ZERO D0 
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ZERO Dl 

MOVE.L #250, D2 
MOVE.L #80, D3 
ZERO D4 
RTS 

ERR_MAKEAREQMEM 
MOVE.L #CANTALL0CMEM,D4 
RTS 



THISREQWINDOW 
THISREQBITEXT 
THISREQPITEXT 
THISREQNITEXT 
_THISREQBTEXT 
- THISREQPTEXT 
THISREQNTEXT 



DC.L 
DC.L 
DC.L 
DC.L 
DC.L 
DC.L 
DC.L 



; WIDTH 

; HEIGHT 

; CLEAR D4, NO ERROR 



;MOVE ERROR CODE TO D4 



POINTER TO WINDOW FOR THIS REQUESTER 
POINTER TO BODY INTUITEXT 
POINTER TO POSITIVE INTUITEXT 
POINTER TO NEGATIVE INTUITEXT 
POINTER TO BODY NULL-TERMINATED TEXT 
POINTER TO POSITIVE NULL-TERMINATED TEXT 
POINTER TO NEGATIVE NULL-TERMINATED TEXT 



The MAKEAUTOREQUEST subroutine. The MAKE- 
AUTOREQUEST subroutine in REQS.ASM prepares the struc- 
tures and performs auxiliary work required to setup for the 
AUTOREQUEST function call. The programmer supplies three 
text declarations and positioning information for the requester. 

In the MAKEAUTOREQUEST subroutine, no special posi- 
tive or negative IDCMPFLAGS are specified. A value is re- 
turned in register DO, which will inform your program of the 
user's response. 

AUTOREQ (Listing 20-2) shows how to use the 
REQS.ASM macros to prepare a simple yes/no choice re- 
quester. Pay special attention to the way messages are ob- 
tained from the requester in the program loop that monitors 
the IDCMP. The MAKEREQ, SAVEREQ, and REQUEST mac- 
ros take over almost all the effort of programming the 
autorequester. These macros also relieve the programmer of 
monitoring the Intuimessages coming back from the 
autorequester. TRUE is returned in DO when the PositiveText 
was selected; FALSE, when the NegativeText was selected. 

The AUTOREQ program shows one way to make the Re- 
quester appear. Simply use the REQUEST macro. You may 
also use the right mouse button (normally used only for Menu 
selection) to produce a Requester. Review the SETDMREQUEST 
function in the Intuition Reference Manual. When a program 
calls that function, an existing Requester is attached to a dou- 
ble-click of the right mouse button. Then if the user double- 
clicks the right mouse button, the Requester (using its existing 
REQUESTER STRUCTURE) appears. The usual messages can 
then be sent to the program, which later calls ENDREQUEST 



U 
U 
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to clear the Requester from the Window. The CLEARDM- 
REQUEST function unattaches the Requester from a double- 
click of the mouse. Experimentation with the Double-Mouse 
Requester (DMRequest) functions is left as an exercise to ambi- 
tious readers. 

A third alternative for making a Requester appear is the 
Intuition REQUEST function, which uses an existing RE- 
QUESTER STRUCTURE and displays the corresponding Re- 
quester image. It also uses the IDCMP for message passing to 
the program. When you ambitiously design beautiful imagery 
and Gadget-laden Requesters, the REQUEST function is the 
most straightforward way to use them. Use of the REQUEST 
function is left as an exercise for the reader. A routine for allo- 
cating the required memory and performing the fill-in function 
should look something like the MAKEAMENU, MAKEAGAD- 
GET, MAKEAWINDOW, and other routines presented in ear- 
lier type-in include files. 

Listing 20-2 demonstrates using the REQS.ASM routines 
and macros to make a two-choice autorequester for an Intu- 
ition window. 

Listing 20-2. AUTOREQ.ASM 

Autorequester demonstration using support from REQS.ASM. 

;NAME: AUTOREQ.ASM BY DAHIEL WOLF 
;COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 
;39/10/87 

BRA _START 

TXT EQU 1 
REQ EQU 1 
WIN EQU 1 

REQXMAX EQU 363 
REQYMAX EQU 60 

INCLUDE "HEADER" 
MAIN 
_BUILDAWINDOW 

MAKEWIN #TITLE, 40, 15, 500, 40, ERROR, WINDOW 

PRINTNEWAT WINDOW, MESSAGE, 5 , 20 , DONE 

MAKEREQ REQMESSAGE.NO, YES, ERROR.-USE MACRO TO SET UP AUTOREQUESTER 

SAVEREQ REQ1;SAVE ADDRESSES OP THE INTUITEXTS 
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LOOP 
MOVE.L WINDOW, A0 

MOVE.L WW.USERPORT(A0),A0 .-LISTEN TO PORT ATTACHED TO THIS WINDOW 
SYSLIB WAITPORT jWAIT FOR A SPECIFIED MESSAGE TO ARRIVE 

MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 

SYSLIB GETMSG J MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

TST.L D0 .-POINTER TO INTUIMESSAGE COMES BACK IN D0 

BEQ LOOP ;NO MESSAGE THERE, SO LOOP 

MOVE.L D0,A0(IF USER PRESSED MOUSE LEFT MOUSE BUTTON THEN 

MOVE.L IM. CLASS (A0),D7 

MOVE.L IM.CODE(A0),D6 

MOVE.L A0.A1 

SYSLIB REPLYMSG 

CMP.L #CLOSEWINDOW,D7;SEE IF USER HAS HIT CLOSEWINDOW BUTTON 

BEQ DONE 

HEREITIS;IT WASN'T THE CLOSE GADGET SO . . . 
REQUEST WINDOW, REQ1 ; SHOW THE REQUESTER 
TST.L D0;WAIT FOR USER REPLY WITH MOUSE 
BNE LOOP; IF USER HIT 'NEGATIVE' BUTTON, THEN DO THIS AGAINI 

ERROR 
DONE 

MOVE.L WINDOW, D0 

BEQ.S QUITNOW 

MOVE.L D0,A0 

INTLIB CLOSEWINDOW 

ZERO D0 
QUITNOW 

RTS 

EVENPC 

WINDOW DC.L 

REQ1 DC.L 0,0,0 ;PTR TO BODY ITEXT, POSITEXT, NEGITEXT 

_THISFONTHITE DC.W 9 

TITLE 
DC.B ' AutoReq by D. Wolf ',0 
EVENPC 

MESSAGE 
DC.B ' Please press the left mouse button somewhere in this Window ', 
EVENPC 

.*».* REQUESTERS **** POSITIVE/NEGATIVE responses 

REQMESSAGE 

DC.B ' THIS IS AN AUTOREQUESTER - QUIT 7 ',0 

EVENPC 
YES 

DC.B ' YES ',0 

EVENPC 
NO 

DC.B ' NO ',0 

EVENPC 
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CHAPTER 21 

An Introduction to 
Amiga Graphics 



The Graphics library makes it simple to draw lines, single 
pixels (picture elements, the smallest units of graphics infor- 
mation) of selected colors, fill a window or screen with color, 
and so on. Some graphics macros are provided in the 
MACROS.ASM listing and are documented with information 
about their use. They include: 

• READPOINT 

• DRAWPOINT 

• RECTFILL 

• DRAWLINE 
• LOADRGB 

The macros call Graphics library functions for single 
pixels, rectangular regions, lines, and color-register maps. 
They're easy to use. You should be able to learn them quickly 
by reading through the program examples provided. A com- 
plete guide to the Graphics library would require another large 
book. This section is intended to be an introduction to graphics. 

In order for the programs later in this chapter to use the 
Graphics library routines, the GFXEQUATES.ASM file must be 
entered. GFXEQUATES.ASM appears in Listing 21-1. Use 
EMACS or your favorite text editor to type in this equate file. 
Save it as: 

DEV:RAMIT/INCLUDES/GFXEQUATES.ASM 
Listing 21-1. GFXEQUATES.ASM 

.*.**.... GFXEQUATES.ASM 
: 03/24/87 

;**» GRAPHICS CONSTANTS 

COMPLEMENT EQU 52 

EXTRA_HALFBRITE EQU 580 

HAM EQU 5800 

HIRES EQU 58000 

INVERSVID EQU 54 

JAM1 EQU 50 

JAM2 EQU 51 

LACE EQU 54 
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;*** GRAPHICS LIBRARY ROUTINE OFFSETS (PARTIAL LIST FROM AMIGA. LIB) 

LVO.BLTTEMPLATE EQU 5FFFFFFDC 
LVO.CLEAREOL EQU $FFFFFFD6 
LVO.CLEARREGION EQU 5FFFFFDF0 
LVO.CLEARSCREEN EQU 5FFFFFFD0 
LVO.DRAW EQU SFFFFFF0A 
LVO. FLOOD EQU SFFFFFEB6 
LVO.GETRGB4 EQU 5FFFFFDBA 
LVO.LOADRGB4 EQU SFFFFFF40 
LVO. MOVE EQU 5FFFFFF10 
LVO.POLYDRAW EQU SFFFFFEB0 
LVO.READPIXEL EQU 5FFFFFEC2 
LVO.RECTFILL EQU ?FFFFFECE 
LVO.SETAPEN EQU $FFFFFEAA 

LVO.SETBPEN EQU 5FFFFFEA4 
LVO.SETDRMD EQU $FFFFFE9E 
LVO.SETRGB4 EQU 5FFFFFEE0 

LVO.WRITEPIXEL EQU 5FFFFFEBC 

.*** A COUPLE OF RASTPORT STRUCTURE OFFSETS 

RP.FGPEN EQU $19 
RP.BGPEN EQU S1A 
RP.OPEW EQU SIB 

RP.DRAWMODE EQU $1C 

;*** A COUPLE OF VIEWPORT STRUCTURE OFFSETS 

VP.COLORMAP EQU $4 

VP. MODES EQU S20 

The RASTPORT Structure 

Most Graphics library routines work with a pointer to a 
RASTPORT structure. Each window and screen has a 
RASTPORT structure (WW.RPORT and SCRN.RASTPORT) so 
the pointer can easily be located by a program. 

The RASTPORT structure contains information about the 
memory layout of the bitmaps in which drawing occurs, and 
about drawing modes and patterns. The program examples in 
Listing 21-2 show how to obtain the pointers to a Window's 
RASTPORT and VIEWPORT. 

Listing 21-2. Examples to identify a Window's RASTPORT and 
VIEWPORT 

EXAMPLE 1. RASTPORT 
STRUCTURE POINTER 
FROM A WINDOW 

START WITH WINDOWS 

ADDRESS 

GET RASTPORT ADDRESS 

FROM WINDOW 

EXAMPLE 2. VIEWPORT 
STRUCTURE POINTER 

FROM A WINDOW 



MOVE! WINDOW.AO 

MOVE.L WW.RPORT(A0),THISRASTPORT 



MOVE.L WINDOWAO 



START WITH WINDOWS 
ADDRESS 



u 

U 
U 
U 
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INTLIB VIEWPORTADDRESS 

MOVE.L DOJHISVIEWPORT 

MOVE.L WINDOW.A0 

MOVE.L WW.RPORT(A0),THISRASTPORT 

MOVE.L WINDOW.A0 

INTLIB VIEWPORTADDRESS 

MOVE.L DOJHISVIEWPORT 



GET VIEWPORT ADDRESS 
; FROM WINDOW 

EXAMPLE 3. BOTH 

START WITH WINDOW 

POINTER 

SWE RASTPORT POINTER 

AT LABEL 

GET WINDOW POINTER 

SWE VIEWPORT POINTER 

AT LABEL 

DATA DECLARATION 
LATER IN PROGRAM 



THISRASTPORT DC.L 
THISVIEWPORT DC.L 



n 

n 
n 
n 
n 



Drawing into a RASTPORT 

The Graphics library routines for single-point drawing and 
line drawing are similar to the operation of a computer plotter. 
The graphics routines use this plotter metaphor to simplify 
programming simple drawing. 

Imagine the process of drawing a line using a plotter. The 
plotter's pen is in the up position, not touching the paper. You 
give the plotter an instruction to move the pen to the starting 
point of your line. A second command lowers the pen to the 
paper. A third command moves the pen to the end of the line. 
Figure 21-1 illustrates this plotter concept. 

Figure 21-1. Plotter Analogy for Graphics Drawing Functions 




AMIGA GRAPHIC PENS 



DRAHM0DE=JAM1 
CUSES A PEN) 



MINDOM 



CURRENT PEN POSITION- X, V, 



MOVE HAS PEN 'UP' 
DRAU HAS PEN 'DOWN' 



TO ORAM LINE: 



HfflSE PEN TO STARTING 
POINT X a Vg 

SBSB FROM X S V S T0 
END POINT X„V, 
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Table 21-2 contains a list of some Graphics library func- 
tions with parameter-passing register specifications you can 
use for more complex graphics. (This table lists only routines 
used in programs in this book.) 

Table 21-2. Graphics Library Functions with Parameter Register 
Specifications 

Drawing Color Control Functions 



Function 






Name Description 


Parameters 


Registers 


SETAPEN Set foreground pen 


(RPColor Reg) 


A0,D0 


SETBPEN Set background pen 


(RP,Color Reg) 


A0,D0 


SETOPEN Set outline pen 


(RP,Color Reg) 


A0,D0 


SETDRMD Set drawing mode 


(RP,Mode) 


A0,D0 


Mode = JAM1, JAM2, COMPLEMENT, INVERSVID 




Line Drawing Functions 






Function 






Name Description 


Parameters 


Registers 


MOVE Move Pen to x, y 


(RP,x,y) 


A0,D0,D1 


DRAW Draw to x, y 


(RP,x,y) 


A0,D0,D1 


POLYDRAW Draw List of Lines 


(RP,NumPairs,List) 


A0,D0,A1 


Point Drawing Functions 






Function 






Name Description 


Parameters 


Registers 


WRITEPIXEL Set Pixel Color 


(RP,x,y) 


A0,D0,D1 


READPIXEL Read Pixel Color 


(RP,x,y) 


A0,D0,D1 



Region Filling Functions 

Function 

Name Description Parameters Registers 

FLOOD Flood within boundary(RP,Mode,x,y) A0,D2,D0,D1 

Mode = Fill nonmatching pixels up to boundary of different color 

Mode = 1 Fill only matching color pixels with new color 

RECTFILL Rectangle fill (RP,xMN,yMN,xMX,yMX) A0,D0-D3 

SETRAST Fill entire raster (RP,Color Reg) A0,D0 

Color Register Control 

Function 

Name Description Parameters Registers 

SETRGB4 Set 1 Color Register (VP,CReg,Red,Grn,Blu) A0,D0-D3 

LOADRGB4 Set >1 Color Register (VP, CTable, How Many) A0,A1,D0 

Listing 21-3, GFX1.ASM, is a short program that opens an 
Intuition window and uses the window's RASTPORT structure 
to draw single pixels and lines. Since all programs are in the 
Workbench screen, they're limited to four colors. 
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Listing 21-3. GFX1.ASM 

##;GFX1.ASM BY DANIEL WOLF 

.-COPYRIGHT 1987 BY COMPUTE! PUBLICATIONS 

,-09/10/87 



BRA _START 

MAT EQU 1 

TXT EQU 1 
HEX EQU 1 
GFX EQU 1 



; INCLUDE MATH TO GET HEXCONVERT ROUTINE 

;A FEW INTUITEXT MESSAGE WILL APPEAR 

; WE'LL HAVE HEX OUTPUT ON THE PROPORTIONAL GADGET 

,-WE NEED THE GRAPHICS LIBRARY AND GFXEQUATES 



WBC EQU 1 ;LETS MAKE SURE THERE'S A CONSOLE FOR DOS I/O FROM WORKBENCH 

INCLUDE "HEADER" 

MAIN 
DOSPRINT STDOUT,#MYMESSAGE ;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 
ZERO D0 

MOVEA.L COMMAND, A0 ; PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'7',(A0) ,-IF FIRST CHARACTER IS 7 THEN 

BNE.S _BUILDAWINDOW 
BRA USAGE 

_BUILDAWINDOW 
LEA NEWWINDOW.A0 
INTLIB OPENWINDOW 
TST.L D0 
BEQ ERROR 
MOVE.L D0, WINDOW 
MOVE.L D0.A0 
MOVE.L WW.RPORT(A0),RP 



; WINDOW OPENED HAS ITS POINTER IN D0 



PRINTNEWAT WINDOW, MSG1 , 90 , 50, DONE 



;A MESSAGE I 



SETAPBN RP,#1 ;SET COLOR REGISTER #1 

RECTFILL RP,#10,#10,#20,#20;DRAW A RECTANGLE 

SETAPEN RP,#2;COLOR *2 

RECTFILL RP, #15, #15, #30, #30 

SETAPEN RP,#3;COLOR #3 

RECTFILL RP, #25, #25, #70, #70 

PRINTNEWAT WINDOW, MSG2, 90, 140, DONE/MESSAGE 



SETAPEN RP,#1; COLOR 1 
DRAWPOINT RP,#100,#100|DRAW 
SETAPEN RP, #2; COLOR 2 
DRAWPOINT RP, #100, #110 
SETAPEN RP, #3; COLOR 3 
DRAWPOINT RP, #100, #120 



SETAPEN RP,#2 

DRAWLINE RP, #101, #101, #130, #130 



LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S LOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 



ONE PIXEL AT 100,100 



CMP.L #CLOSEWINDOW,D2 
BEQ DONE 



; LISTEN TO PORT ATTACHED TO THIS WINDOW 
,-WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



;MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

; POINTER TO INTUIMESSAGE COMES BACK IN D0 

; NO MESSAGE THERE, SO LOOP 

,- POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

,-CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

/MENU AND MENUITEM APPEAR HERE 

,-KEYS APPEAR HERE 

; QUICK, SEND MESSAGE BACK NOW1 



;IF ITS A CLOSEWINDOW MESSAGE, THEN DO SO. 
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DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
1$ 

PULLREG D0 
QUITNOW 

RTS 

ERROR 

DOSPRINT STDOOT, #ERRORTEXT 

MOVEQ #CANTOPENWINDOW,D0 

RTS 
USAGE 

DOSPRINT STDOUT,#USAGETEXT 

BRA DONE 

;***** TEXT DATA DECLARATIONS ***** 

MYMESSAGE 

DC.B 10,' GFX1 by D. Wolf Copyright 1987 by Compute! Publications ',10,0 

EVENPC 
MYWINDOWTITLE 

DC.B ' GPX1 by D.Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage: GFXl',10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MSG1 

DC.B 'A FEW RECTANGULAR FILLS ',0 

EVENPC 
MSG2 

DC.B 'A FEW PIXELS AND A LINE',0 

EVENPC 

WINDOW DC.L ; POINTER TO WINDOW STRUCTURE 

RP DC.L ;POINTER TO WINDOW'S RASTPORT STRUCTURE 

_THISFONTHITE DC.W 9 [DEFAULT FONT HEIGHT 

NEWWINDOW 
DC.W 
DC.W 
DC.W 640 
DC.W 190 
DC.B -1 
DC.B -1 

DC.L CLOSEWINDOW 

DC . L WINDOWDRAG I WINDOWDEPTH I WINDOWCLOSE 1 SMART_REFRESH 
DC.L 
DC.L 

DC.L MYWINDOWTITLE 
DC.L 
DC.L 

DC.W 140 iBE CAREFUL MIN HEIGHT AND WIDTH AREN'T 

DC.W 143 :SO SMALL THAT THE RELATIVE HEIGHT AND WIDTH 

DC.W 640 ;OF THE GADGET CAN BECOME LESS THAN ZERO 

DC.W 400 ;OR YOU'LL BE SORRYI (COULD ELIMINATE SIZING INSTEAD) 

DC.W WBENCHSCREEN 
END 



u 
u 
u 

u 

u 
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Listing 21-4, GFX2.ASM, is a program that performs some 
line and area drawing, then alters the colors used by the win- 
dow's RASTPORT. 

Listing 21-4. GFX2.ASM 

##;GFX2.ASM BY DANIEL WOLF 

.•COPYRIGHT 1987 BY COMPUTEl PUBLICATIONS 

,-09/1.3/87 

BRA _START 

MAT EQU 1 ; INCLUDE MATH TO GET HEXCONVERT ROUTINE 

GAD EQU 1 ; WE'LL LET A PROPORTIONAL GADGET CONTROL SOME GRAPHICS 

TXT EQU 1 ;A FEW INTUITEXT MESSAGE WILL APPEAR 

HEX EQU 1 ; WE'LL HAVE HEX OUTPUT ON THE PROPORTIONAL GADGET 

GFX EQU 1 ;WE NEED THE GRAPHICS LIBRARY AND GFXEQUATES 

WBC EQU 1 ;LETS MAKE SURE THERE'S A CONSOLE FOR DOS I/O FROM WORKBENCH 

INCLUDE "HEADER" 

MAIN 
DOSPRINT STDOUT,#MYMESSAGE ;IP INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 
ZERO D0 

MOVEA.L COMMAND, A0 ;PUT ADDRESS OF COMMAND LINE IN A0 

CMPI.B #'7',(A0) ;IF FIRST CHARACTER IS ? THEN 

BNE.S BUILDAWINDOW 
BRA USAGE 

_BUILDAWINDOW 
LEA NEWWINDOW.A0 
INTLIB OPENWINDOW 
TST.L D0 
BEQ ERROR 

MOVE.L D0, WINDOW ; WINDOW OPENED HAS ITS POINTER IN D0 

MOVE.L D0,A0 
MOVE.L WW.RPORT(A0),RP 
MOVE.L WINDOW, A0 
INTLIB VIEWPORTADDRESS 
MOVE.L D0,VP 

PRINTNEWAT WINDOW, MSG1, 90, 50, DONE ;A MESSAGEI 

SETAPEN RP,#1 ;SET COLOR REGISTER #1 

RECTFILL RP,#10,#10,#20,#20;DRAW A RECTANGLE 

SETAPEN RP, #2; COLOR #2 

RECTFILL RP, #15, #15, #30, #30 

SETAPEN RP, #3; COLOR #3 

RECTFILL RP, #25, #25, #70, #70 

PRINTNEWAT WINDOW, MSG2 , 90 , 120 , DONE ; MESSAGE 

SETAPEN RP,# It COLOR 1 

DRAWPOINT RP,#100,#100jDRAW ONE PIXEL AT 100,100 

SETAPEN RP,#2;COLOR 2 

DRAWPOINT RP, #100, #110 

SETAPEN RP,#3;COLOR 3 

DRAWPOINT RP, #100, #120 

MOVE . L #TICKSPERSECOND, Dl 
ASL.L #2,D1 
DOSLIB DELAY 

SETAPEN RP,#0;NOW CLEAR THE WHOLE WINDOW 

RECTFILL RP,#10,#10,#630,#180;AND LETS HAVE FUN WITH THE PGADGET 

_BUILDAGADGET ; DEFAULT WILL BE A HORIZONTAL PROPORTIONAL GADGET 

MOVE.W #20,D4 ;LEFTEDGE FOR GADGET 

MOVE.W #20, D5 ;TOPEDGE FOR GADGET 

MOVE.W #-100, D6 .-RELATIVE WIDTH, 100 PIXELS LESS THAN WINDOW 

MOVE.W #-120, D7 .-RELATIVE HEIGHT, 120 PIXELS LESS THAN WINDOW 
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BSR MAKEAPROPGADGET 
MOVEA.L WINDOW, A0 
MOVEA.L _THISGADGET,A1 
MOVE.L A1,_PIRSTGADGET 

CHANGEGADGFLAGS 
"MOVE.W GADG.FLAGS(Al) ,D0 
ORI.W #GRELWIDTHIGRELHEIGHT, 

MOVE.W D0,GADG.PLAGS(M) 

NOWADDTHEGADGET 
"ZERO D0 
MOVE.W #-l,D0 
INTLIB ADDGAOGET 

MOVE.L FIRSTGADGET.A0 
MOVE.L WINDOW, Al 

INTLIB REPRESHGADGETS 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 
SYSLIB GETMSG 
TST.L D0 
BEQ.S LOOP 
MOVE.L D0.A1 
MOVE.L IM.CLASS(A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIPIER(A1),D4 
SYSLIB REPLYMSG 



fMAKE THE GADGET, INTUITEXT, AND BORDER 

) ROUTINE LEAVES POINTER TO GADGET STRUCTURE HERE 
I ITS THE FIRST ONE, A SPECIAL POINTER FOR WINDOW 

.•HERE'S HOW TO USE CUSTOM FLAGS COMBINATIONS 
;IN SPITE OF THE DEFAULT ' MAKEAGADGET ' FLAGS 
;(SET THE RELATIVE WIDTH AND HEIGHT FLAGS) 
; BRING FLAGS OUT, 'OR' AS DESIRED, PUT 'EM BACK 



;THIS ASSURES ITS AT THE TOP OF THE LIST 

; ATTACH GADGET TO WINDOW STRUCTURE'S GADGET LIST 



;PASS TWO ADDRESS PARAMETERS TO THE REFRESH ROUTINE 
J NOW MAKE THE GADGET APPEAR I 



; LISTEN TO PORT ATTACHED TO THIS WINDOW 
;WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



; MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 

; POINTER TO INTUIMESSAGE COMES BACK IN D0 

;NO MESSAGE THERE, SO LOOP 

.•POINTER TO INTUIMESSAGE CAME BACK, USE IN Al 

,-CLOSEWINDOW AND GADGET MESSAGES APPEAR HERE 

)MENU AND MENUITEM APPEAR HERE 

;KEYS APPEAR HERE 

; QUICK, SEND MESSAGE BACK NOW! 



CMP.L #CLOSEWINDOW, D2 

BEQ DONE 

CMP.L #GADGETUP,D2 

BNE LOOP 

BSR DOGADGET 

BRA LOOP 

DONE 

ZERO D0 
QUIT 

PUSHREG D0 

MOVE.L WINDOW, D0 

BEQ.S 1$ 

MOVE.L D0,A0 

INTLIB CLOSEWINDOW 
1$ 

PULLREG D0 
QUITNOW 

RTS 

ERROR 

DOSPRINT STDOUT,#ERRORTEXT 

MOVEQ #CANTOPENWINDOW,D0 

RTS 
USAGE 

DOSPRINT STDOUT, #USAGETEXT 

BRA DONE 

DOGADGET 
PUSHALL 
MOVEA.L FIRSTGADGET,A0 



,IF ITS A CLOSEWINDOW MESSAGE, THEN DO 
,-THIS ISN'T A CLOSE OR A GADGETUP 



fTHIS CODE EXECUTED IF GADGET TOGGLED 



!USE GADGET STRUCTURE TO 
MOVEA.L GADS.SPECIALINFO(A0),A0;FIND THE PROPINFO SUB-STRUCTURE POINTER 
ZERO D0 

MOVE.W PI.HORIZPOT(A0),D0 fAND THE VALUE OF THE 'POT' VARIABLE 
MOVE.W D0.POTVALUE 
BSR HEXCONVERT 
ZERO D0 

MOVE.W POTVALUE.D0 
LSR.W #4,D0 
LSR.W #3,D0 
MOVE.W D0.SIZE 
SETAPEN RP,#0 
RECTFILL RP, #2, #135, #600, #180 ,-CLEAR THE DRAWING AREA 



;NOW DECODE AND PRINT VALUE TO CLI WINDOW 



NOW DO SOME GRAPHICS BASED ON THE POT VALUE 



u 
u 
u 
u 
u 
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SETAPEN RP,#3 

RECTPILL RP, #5, #150, SIZE, #180 ;DRAW RECTANGLE PROPORTIONAL TO POT VALUE 

SETAPEN RP,#2 

DRAWLINE RP, #5, #140, SIZE, #140 [DRAW LINE PROPORTIONAL TO POT VALUE 

SETAPEN RP,#1 

DRAWPOINT RP, SIZE, #132 ;DRAW PIXEL AT X POSITION PROPORTIONAL TO POT 

ZERO D0 

MOVE.W SIZE, D0 

MOVE.W D0.LASTCOL 

LOADRGB VP,COLRS,4 

ZERO D0 

MOVE.W SIZE.D0 

BSR HEXCONVERT 

PULLALL 

RTS 

;***** TEXT DATA DECLARATIONS ***** 

MYMESSAGE 

DC.B 10,' GPX2 by D. wolf Copyright 1987 by Computel Publications ',10,0 

EVENPC 
MYWINDOWTITLE 

DC.B ' GFX2 by D. Wolf ',0 

EVENPC 
USAGETEXT 

DC.B 'Usage: GFX2',10,0 

EVENPC 
ERRORTEXT 

DC.B 10, 'Sorry, cannot open window ',10,0 

EVENPC 
MSG1 

DC.B 'A FEW RECTANGULAR FILLS' ,0 

EVENPC 
MSG2 

DC.B 'A FEW PIXELS', 

EVENPC 

WINDOW DC.L ; POINTER TO WINDOW STRUCTURE 

RP DC.L ; POINTER TO WINDOW'S RASTPORT STRUCTURE 

VP DC.L .-POINTER TO WINDOW'S VIEWPORT STRUCTURE 

_FIRSTGADGET DC.L (POINTER TO GADGET'S STRUCTURE IN MEMORY 

_THISFONTHITE DC.W 9 .-DEFAULT FONT HEIGHT 

POTVALUE DC.W 
SIZE DC.W 
B 
COLRS 

DC.W SFFF 

DC.W $000 

DC.W $00F 
LASTCOL 

DC.W $0F0 

NEWWINDOW 
DC.W 
DC.W 
DC.W 640 
DC.W 190 
DC.B -1 
DC.B -1 

DC.L CLOSEWINDOW1GADGETDOWN1GADGETUP 

DC . L WINDOWDRAG 1 WINDOWDEPTH1 WINDOWCLOSE 1 SMART_REFRESH 
DC.L 
DC.L 

DC.L MYWINDOWTITLE 
DC.L 
DC.L 

DC.W 140 ;BE CAREFUL MIN HEIGHT AND WIDTH AREN'T 

DC.W 140 ,-SO SMALL THAT THE RELATIVE HEIGHT AND WIDTH 

DC.W 640 ,-OF THE GADGET CAN BECOME LESS THAN ZERO 

DC.W 400 ;OR YOU'LL BE SORRY1 (COULD ELIMINATE SIZING INSTEAD) 

DC.W WBENCHSCREEN 
END 
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Intuition Screens 

One of the limitations of the programs introduced up to this 
point is that all their windows use the Workbench screen. This 
screen is configured by the Amiga operating system to have a 
640 X 200 resolution and four colors (two bitplanes, each with 
640 X 200 pixels) or 640 X 400 pixels, if interlaced. 

Custom Screens for more Colorful Graphics 

All windows that open in a screen inherit its resolution and 
number of available colors. The windows that open in the 
Workbench screen, therefore, can have, at most, four colors. 
The Amiga can produce many different combinations of dis- 
play resolution and many colors. In order to maximize the 
flexibility of the graphics display in your programs, you can 
open custom screens with the resolution and colors you desire. 
Opening a screen is similar to opening a window. A NEW- 
SCREEN structure is filled with appropriate screen data and a 
call is made to the OPENSCREEN Intuition library function. 

The NEWSCREEN Structure 

The NEWSCREEN structure is fairly simple. Like other Intu- 
ition display structures, it's composed of fields. Some of these 
fields are for positioning and sizing parameters. There are also 
fields to contain a pointer to a title text string and an optional 
custom bitmap. Another field is an optional pointer to a font 
for use when text is drawn on the screen. The other field of 
interest provides for combinations of VIEWMODES flags, 
which specify the screen resolution and number of bitplanes. 

The relationship between colors and bitplanes is as fol- 
lows: Each additional bitplane multiplies the number of colors 
available to the screen by two. The minimum number of bit- 
planes is one for a screen with just two colors (foreground and 
background). Two bitplanes provide four colors. I 

To see how Amiga graphics work, pretend that a screen is •*—- ' 
only two pixels wide by two pixels high and one bitplane 
deep, like a 2 X 2 array. Any element of the array can hold I i 
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either a zero or a one. A zero causes that element of the array 
(pixel) to be drawn in the background color, while a one 
causes a pixel to be drawn in the foreground color. What 
really happens is that each element of the array is a pointer to 
a special color register (the Amiga has 32 color registers). A 
zero points to color register (the background color), and that 
pixel will be drawn with the color in color register 0. Since 
this is the background color, it will be invisible. A one will 
point to color register 1, and that pixel will be drawn in what- 
ever color is in color register 1 (the foreground color). Since 
each element of the one-bitplane array can hold only a zero or 
a one, it's limited to pointing to only two color registers. This 
explains why a one-bitplane screen has only two colors. 

Now lets consider what happens if you add another 
bitplane. You now have two arrays, each two elements wide 
by two elements high. Think of them as being one right on 
top of another, with each element in the top array being 
paired with its corresponding element in the bottom array. 
Since each individual element can hold a zero or a one, you 
now have four choices (00, 01, 10, 11 — the first number of 
each pair comes from the top array; the second; from the bot- 
tom array). As you can see, with two bitplanes, you can point 
to four color registers, so you can display four different colors. 
Each additional bitplane doubles the number of color registers 
you can point to, thereby doubling the number of possible 
colors. 

Of course, a screen on an Amiga is much larger than two 
pixels wide by two pixels high, but the idea is exactly the 
same — just think of much bigger arrays. Each bitplane of a 
low-resolution, noninterlaced screen is a 320 X 200 array, 
while a bitplane of a high-resolution, interlaced screen is a 
640 X 400 array. A large number of bitplanes uses a very 
large amount of memory. Since all of this memory must be 
chip memory (in the first 512K of the Amiga's memory), you 
can see why conserving chip memory is so important. 

Table 21-3. shows valid combinations of screen param- 
eters to use in the NEWSCREEN structure. 
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Table 21-3. Custom Screen Sizes, Parameters, and Memory 

Usage '"> — ' 

VIEWMODES Size(WXH) Depth Colors Memory Usage . — 

LORES 320 X 200 1 2 8K Lj 

2 4 16K 

3 8 24K 



4 16 32K i I 

5 32 40K ' — 

LORESIINTERLACE 320 X 400 1 2 16K 

2 4 32K 

3 8 48K 

4 16 64K 

5 32 80K 

HIRES 640 X 200 1 2 16K 

2 4 32K 

3 8 48K 

4 16 64K 

HIRESIINTERLACE 640 X 400 1 2 32K 

2 4 64K 

3 8 96K 

4 16 128K 

HAM 320 X 200 Special mode for 4096 colors 

The title is a string of null-terminated text. You should 
follow certain guidelines for designing screen coordinates: 

Standard Intuition screens are the full height and width of 
the video display area. The standard sizes are: 320 X 200, 
320 X 400, 640 X 200, and 640 X 400. The 320-pixel width 
screens can use up to 32 different color registers, each as- 
signed one of 4096 colors. The 640-pixel width screens are 
limited to 16 colors. You're free to open a custom screen of 
nonstandard dimensions (such as a 120 X 120 screen), but 
there are a few restrictions. See the Intuition Reference Manual 
for details. 

The 320-pixel width screen is called lo-res (low resolu- 
tion). The 640-pixel width screen is called hi-res (high resolu- 
tion). A 400-pixel height screen is achieved using interlace 
mode. 
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Interlace mode is a feature of standard broadcast televi- 
sion. The picture on the monitor is provided by scan lines that 
sweep over the screen many times per second, refreshing the 
display. In interlace mode, the scanlines are moved very 
slightly downward on every other frame, or sweep of the 
screen, and another picture is drawn before the phosphors 
have completely faded from the last scan, providing the illu- 
sion of twice the number of lines on the screen. Interlace 
mode causes the Amiga screen to flicker, but judicious choice 
of colors can minimize this effect and result in very sharp 
graphics displays. 

The desired combination of LORES, HIRES, and INTER- 
LACE are placed into the VIEWMODES field of the NEW- 
SCREEN structure. If the field is left empty (equal to zero) 
then a lo-res screen 200 pixels high and 320 pixels wide will 
appear. 

The HAM mode, which allows up to 4096 colors to ap- 
pear on the screen is a very specialized graphics mode and it 
will not be covered here. 

As with windows, it's a matter of choice for the program- 
mer whether to use a special subroutine to open screens or 
just declare the NEWSCREEN structure in the source code. 
Since screens take up large amounts of memory, most pro- 
grams don't open more than one or two of them. 

The NEWSCREEN structure is disposable (it can be 
deallocated when OPENSCREEN is finished), like the NEW- 
WINDOW structure. It's only used by Intuition when opening 
the screen. Tables 21-4 and 21-5 list the definitions of the 
NEWSCREEN and SCREEN structures. 

Table 21-4. Intuition NEWSCREEN Structure 



Symbol: NS 




Size: 32 bytes ($20 bytes) 




Field Size Name 


Offset Description 


Word NS.LEFTEDGE 


Should be 


Word NS.TOPEDGE 


2 Number of pixels from top 


Word NS.WIDTH 


4 Number of pixels wide (320 




or 640) 


Word NS.HEIGHT 


8 Number of pixels high (up 




to 200; or 400, if interlaced) 
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Field Size 

Word 


Name 
NS.DEPTH 


Offset 

8 


Byte 


NS.DETAILPEN 


10 


Byte 


NS.BLOCKPEN 


11 


Word 


NS.VIEWMODES 


12 


Word 
Long 


NS.TYPE 
NS.FONT 


14 
16 


Long 


NS.DEFAULTTITLE 


20 


Long 
Long 


NS.GADGETS 24 
NS.CUSTOMBITMAP 28 



Description 

Number of bitplanes in this 

screen 

Color register number for 

gadgets and title text 

Color register number for 

block fills 

Rags for the screens display 

modes 

Workbench, custom screen 

Pointer to font STRUCTURE 

(0 is the default) 

Pointer to null-terminated 

title 

Should be 

Pointer to your bitmap, if 

any 



Table 21-5. Intuition SCREEN Structure 



Symbol: 


SCRN 






Size: 346 


bytes ($15 A bytes) 






Field Size Name 


Offset Description 


Long 


SCRN.NEXT 





Pointer to next screen 
structure 


Long 


SCRN.WINDOW 


4 


Pointer to first window in 
screen 


Word 


SCRN.LEFTEDGE 


8 


Number of pixels from 
left edge 


Word 


SCRN.TOPEDGE 


10 


Number of pixels from 
top edge 


Word 


SCRN.WIDTH 


12 


Number of pixels wide 


Word 


SCRN.HEIGHT 


14 


Number of pixels high 


Word 


SCRN.MOUSEX 


16 


Screen mouse position 
from left edge 


Word 


SCRN.MOUSEY 


18 


Screen mouse position 
from top edge 


Word 


SCRN.FLAGS 


20 


Screen flag bits 


Long 


SCRN.TITLE 


22 


Pointer to screen title text 


Long 


SCRN.DEFAULTTITLE 


26 


Pointer for window with 
no screen title 


Byte 


SCRN.BARHEIGHT 


30 


Screen bar height in 
pixels 


Byte 


SCRN.BARVBORDER 


31 


Vertical border thickness 
in pixels 


Byte 


SCRN.BARHBORDER 


32 


Horizontal border thick- 
ness in pixels 



u 
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SCRN.MENUHBORDER 34 



Field Size Name Offset Description 

Byte SCRN.MENUVBORDER 33 Vertical menu border 

thickness in pixels 
Horizontal menu border 
thickness in pixels 
Top window border 
thickness in pixels 
Left window border 
thickness in pixels 
Right window border 
thickness in pixels 
Bottom window border 
thickness in pixels 
Pointer to FONT structure 
for screen 

At this point in the structure is a complete VIEWPORT structure. 

At this point in the structure is a complete RASTPORT structure. 

At this point in the structure is a complete BITMAP structure. 

At this point in the structure is a complete LAYERINFO structure. 



Byte 
Byte 
Byte 
Byte 
Byte 
Long 



SCRN.WBORTOP 

SCRN.WBORLEFT 

SCRN.WBORRIGHT 



35 
36 



37 



SCRN.WBORBOTTOM 38 



SCRN.FONT 



40 



Long 


SCRN.FIRSTGADGET 


326 


Pointer to first gadget 
structure 


Byte 


SCRN.DETAILPEN 


330 


Drawing pen number for 
border 


Byte 


SCRN.BLOCKPEN 


331 


Drawing pen number for 
menu, dragbar 


Word 


SCRN.SAVECOLOR0 


332 


Used by system to save 
the background color 
before a DisplayBeep( ) 
call 


Long 


SCRN.BARLAYER 


334 


Pointer to screen/menu 
bar layer 


Long 


SCRN.EXTDATA 


338 


Pointer to external data 


Long 


SCRN.USERDATA 


342 


Pointer to user data 



Memory Considerations 

Memory allocation is automatic when OPENSCREEN is called, 
but you'll want to know how much is being used. As men- 
tioned previously, it will all be chip memory. To calculate the 
memory that will be allocated for a screen, use the following 
formula: 

Bytes = (WIDTH X HEIGHT X DEPTH) / 8 

A 640 X 200-pixel screen with a depth of three bitplanes 
(DEPTH = 3) uses 48,000 bytes (3 bitplanes of 16,000 bytes). 
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Remember: If your program calls CLOSEWORK- 
BENCH, it must reopen the Workbench later with a call 
to OPENWORKBENCH. 



U 
U 



The screen that uses the largest amount of memory is a screen [_ i 

of 640 X 400 X 4. It uses 128,000 bytes. Since screen display 

must be in chip memory (limited to 512K), programmers must - - 

provide for circumstances in which a large quantity of memory | j 

isn't available. If one program is using a large screen like the 

one described above, another program may not be able to get - 

the chip memory it needs, causing it to fail. | | 

It's possible to gain some display memory by closing the 
Workbench screen, but that only works if no windows are 
open in the Workbench. 



If a screen can't be opened, the OPENSCREEN function 
will return a in register DO, which can be detected by your 
program code. A successful call to OPENSCREEN yields the 
address of the SCREEN structure in DO. In case of failure, the 
program can either quit, try to open a screen with smaller 
memory requirements, or alert the user to close down other 
applications to provide more memory and try again. 

Closing the Custom Screen 

A custom screen is not provided with a close gadget. The drag 
bar and the front/back gadgets are present (though perhaps 
not visible) at the top. The drag bar can be used to slide the 
screen down to reveal the Workbench screen behind it. The 
front/back gadgets swap screens when clicked with the 
mouse. You can also type the Left Amiga-N combination (on 
the Amiga 500, the left Amiga key has been changed to a 
Commodore logo key) to swap screens. 

To close a screen requires a separate call to 
CLOSESCREEN. Interestingly enough, there is no IDCMP at- 
tached to the screen alone, so there's no explicit way to get ; j 
messages through to the program saying the user wishes to I — I 
close the screen. To make matters worse, you may not attach 
any of your own gadgets to the screen. j" | 
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The SCREEN structure obtained by a call to OPEN- 
SCREEN contains information that can be used by your 
program to close the screen: the SCRN.MOUSEX and 
SCRN.MOUSEY fields in the SCREEN structure. When your 
program detects certain values in those fields (such as or 
639 for SCRN.MOUSEX), the program can react by calling 
CLOSESCREEN. An alternative is to have a window open up 
that has an IDCMP for user I/O. 

A good combination for convenient display is a screen 
with a BACKDROP window as large as the screen. A BACK- 
DROP window is a window that stays behind all other win- 
dows on a screen. It does not have a depth arrangement 
gadget. Needless to say, a screen can have only one BACK- 
DROP window. Using SMART_REFRESH on the BACKDROP 
window will protect it from being trashed by menus, request- 
ers, and other objects that are drawn on it by the system. This 
combination is used in the example program in Listing 21-5. A 
screen of 640 X 400 X 4 is opened, so its BACKDROP win- 
dow can display 16 colors. The demo also calls some Intuition 
routines that manipulate screens, windows, and their title bars. 
The SETWINDOWTITLES, SHOWTITLE, SCREENTOFRONT, 
and other routines can add professional polish to programs 
that have multiple windows and screens. 



Listing 21-5. SCREEN.ASM 



; SCREEN. ASM BY DANIEL WOLF 

;COPYRIGHT 1987 By COMPUTEl PUBLICATIONS 

;09/10/87 

BRA _START 

GFX EQU 1 

MEN EQU 1 

WIN EQU 1 

TXT EQU 1 

WBC EQU 1 

INCLUDE "HEADER" 

;«•* EQUATES *** 

SCREENWIDTH EQU 640 

SCREENHEIGHT EQU 400 

SCREENSIZE EQU SCREENWIDTH/8*SCREENHEIGHT 

DEPTH EQU 4 

MASK EQU (1<<DEPTH)-1 

COLRS 

DC.W $FFF,$00F,500E,5F00 

DC.W $00C,$00B,$00A,$009 

DC.W 5008, 5007, $006, $005 

DC.W $004, $003, $002, $001 

MAIN 
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SETUP | 



MOVE.L #NEWSCREEN,A0 

INTLIB OPENSCREEN 

MOVE.L D0, SCREEN 

BNE.S 1$ }NO ERROR, GOT AN ADDRESS BACK 

DOSPRINT STDOUT,#NOSCREEN 

MOVEQ #CANTOPENSCREEN, D0 

BRA ERROR ;OOPS, NOT ABLE TO OPEN SCREEN 



u 



1$ 

LEA THISFLAGS.A0 i I 

MOVETL #BACKDROP1BORDERLESSIACTIVATE1SMART_REFRESH,(A0) 

LEA _THISCREEN,A0;SET WINDOW INTO SCREEN L_J 

MOVE.L SCREEN, (A0) 

LEA _THISTYPE,A0; CHANGE WINDOW TYPE 

MOVE.W #CUSTOMSCREEN, (A0) 

MAKEWIN #WINTITLE,0,0,SCREENWIDTH,SCREENHEIGHT, ERROR ;NOW MAKE WINDOW 

MOVE.L D0, WINDOW 

MOVE.L D0.A0 

MOVEA.L WW.RPORT(A0),A1 

MOVE.L Al.RP 

MOVE.L SCREEN, A0 

LEA SCRN. VIEWPORT (A0),A1 

MOVE.L Al.VP (STASH IMPORTANT POINTERS FOR SCREEN 

MENUS 

MITEMLIST ITEM00 , ITEM01 , ITEM02 ,0,0,0,0,0,2 

MAKEMEN MEN0CMDS , MEN0MUEX , MEN0TITLE, DONE 

MOVE.L Dl, MENU0 

MOVE.W #5,D0 ;LEFT POS MENU 

MOVE.W #90, Dl ;WIDTH MENU TITLE 

BSR CREATEMENU 

MENUATTACH 
MOVE.L WINDOW, A0 
MOVE.L _MENU0,A1 
INTLIB SETMENUSTRIP 

LOOP 
MOVE.L WINDOW, A0 
MOVE.L #SFFFF,D0 
INTLIB ONMENU 
MOVE.L WINDOW, A0 
MOVE.L WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
MOVE.L WINDOW, A0 
MOVE . L WW . USERPORT ( A0 ) , A0 
SYSLIB GETMSG 
TST.L D0 
BEQ RELOOP 
MOVE.L D0.A1 
MOVE.L IM. CLASS (A1),D2 
MOVE.W IM.CODE(Al),D3 
MOVE.W IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 
CMP.L #CLOSEWINDOW,D2 
BEQ DONE 

CMP.L *MENUPICK,D2 
BNE RELOOP 
ZERO D0 
MOVE.W D3.D0 
BSR MENUEVENT 

HANDLEMENU0 

CMPI.W #0,D0 

BNE RELOOP 

CMPI.W #2,D1 

BEQ DONE 

CMPI.W #0,D1 

BNE.S 1$ 

BSR SDRAW 

BRA RELOOP 
1? 

CMPI.W tl.Dl 

BNE RELOOP 

BSR ROLLCOLORS . 
RELOOP 

BRA LOOP 
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SDRAW 
MOVE.L WINDOW, A0 
ZERA Al 
ZERA A2 
INTLIB SETWINDOWTITLES ; CLEAR WINDOW AND SCREEN TITLES 

MOVE.L SCREEN, A0 

ZERO DO ;ZERO HER MEANS SCREEN BAR IN BACK OF BD WINDOW 

INTLIB SHOWTITLE ;PUT SCREEN BAR IN BACK OF BACKDROP WINDOW 

MOVE.L RP.D7 

LOADRGB VP,COLRS,MASK+l 

SETDRMD D7,#JAM1 

SETAPEN D7,#5 

RECTFILL D7 , #0, #0, #SCREENWIDTH-1 , #SCREENHEIGHT-1 

GFXPOINT #300, #20 
GFXLIB MOVE.D7 

SETOPEN D7,#2 

SETAPEN D7,#2 ;DRAW WITH PEN #2 (SAME AS OUTLINE PEN) 

MOVE.L #9, D0; THERE WILL BE 9 POINTS 

LEA POINTLIST.A0 

GFXLIB POLYDRAW.D7 ;NOW DRAW LINES CONNECTING 9 POINT POLYGON 

;IN OUTLINE PEN COLOR TO CONTROL THE FILL 

SETAPEN D7,#0 jFILL WITH COLOR #0 (WHITE) 

GFXPOINT #300, #22 ; FLOOD FROM THIS POINT OUTWARD 

MOVEQ.L #0,D2 ;IN MODE 

GFXLIB FLOOD, D7 ; FLOOD OUT TO PIXEL COLOR=OUTLINE PEN COLOR 

SETAPEN D7,#2 [DRAW WITH SAME COLOR AS OUTLINE PEN 

DRAWLINE D7,#80,#0,#520,#0 ;TO CONTAIN THE FILL WHICH COMES BELOW 
DRAWLINE D7, #520, #0, #520, #200 
DRAWLINE D7, #520, #200, #80, #200 
DRAWLINE D7,#80,#2O0,#80,#0 

GFXPOINT #90, #1 (PICK A POINT FROM WHICH TO FLOOD 

MOVEQ.L #0,D2 ,-PICK FLOOD MODE 

SETAPEN D7,#3 ;PICK PEN FOR FLOOD (COLOR #3) 

GFXLIB FLOOD, D7 ; FLOOD OUT TO COLOR=OUTLINE PEN COLOR 

RTS 

ROLLCOLORS 

LEA.L COLRS,A3 

ZERO D5 
ROLLCOLOR 

MOVEQ.L #2,D3 
ADDACOLOR 

ADD.W #S1,0(A3,D3.W) 

ADDQ.W #2,D3 

CMPI.W #32, D3 

BLT.S ADDACOLOR 

MOVE.L #TICKSPERSEC0ND/32,D1 

DOSLIB DELAY 

LOADRGB VP,COLRS,MASK+l 

ADDQ.W #1,D5 

CMPI.W #5100,D5 

BLT.S ROLLCOLOR 

MOVEA.L SCREEN, A0 

TST.W SCRN.MOUSEX(A0) 

BEQ.S ROLLCOLORS 
ENDROLLCOLORS 

RTS 

DONE 
QUIT 

MOVE.L MENU0.D0 

BEQ.S 1? 

MOVE.L WINDOW, A0 

INTLIB CLEARMENUSTRIP 
15 

MOVE.L WINDOW, D0 

BEQ.S 3$ 
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MOVE.L D0.A0 

INTLIB CLOSEWINDOW 
3$ 

MOVE.L SCREEN, D0 

BEQ.S 4$ 

MOVE.L D0,A0 

INTLIB CLOSESCREEN 
4? 
DONEALL 

ZERO D0 
ERROR 

RTS 

.*•* DATA STUFF *** 
EVENPC 

USAGE 

DC.B 10, 'usage : SCREEN', 10,0 

EVENPC 
NOSCREEN 

DC.B 10, 'Sorry, could not open the 700x440x4 screen. ', 10,0 

EVENPC 
MYMESSAGE 

DC.B 10, 'SCREEN by D. Wolf Copyright 1986 by Compute! Publications' ,10,10, t 

EVENPC 

STACK DC.L 

NEWSCREEN DC.W 0,0,SCREENWIDTH,SCREENHEIGHT, DEPTH 
DC.B MASK.0 
DC.W HIRES 1 LACE 
DC.W CUSTOMSCREEN 
DC.L 0,0,0,0 

EVENPC 

SCREEN DC.L 

VP DC.L 

RP DC.L 

OUTPUT DC.L 

XWIDTH DC.L 5C0000042 

YWIDTH DC.L $C0000042 

SCREENX DC.W 
SCREEN* DC.W 
COUNT DC.W 

MAXIMUM DC.W 16 
LASTCOL DC.W 
EVENPC 

MEN0TITLE 

DC.B 'PROJECT',0 

EVENPC 
ITEM00 

DC.B ' DEMO ' ,0 

EVENPC 
ITEM01 

DC.B ' ROLLCOLORS ',0 

EVENPC 
ITEM02 

DC.B ' QUIT ',0 

EVENPC 
MEN0CMDS 

DC.B 'DRQ' 

EVENPC 
MEN0MUEX 

DC.L $6, $5, $3 

EVENPC 
WINDOW DC.L 
_MENU0 DC.L 
MYLACE DC.L 
WINTITLE DC.B • SCREEN by D. Wolf ',0 

EVENPC 

THISFONTHITE DC.W 9 



u 
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POINTUST 
DC.W 300,20 
DC.W 350,80 
DC.W 500,90 
DC.W 350,100 
DC.W 300,160 
DC.W 250,100 
DC.W 100,90 
DC.W 250,30 
DC.W 300,20 



n 
n 
n 
n 



277 



u 
u 



u 
u 



We 



<*m 



m 



^^^^^SiflWIHI 






wife 



besSp 






i?v*«s«*«? 






pi"*\ \l K \ I Mali 

MS 







* ■■vyoB 



^i 



:^ : .-'*l&'--i«k: 



$l^ii§ 



J - * BT - - 






■ttfHHT 










^K^^ 






*<«lB 







u 
u 



u 
u 



n 
n 
n 



rn 



n 



CHAPTER 22 

Using Floating-Point 
Numbers 



The Amiga has three libraries of routines for floating-point 
math operations on floating-point numbers. While integers 
represent whole numbers within a circumscribed range, float- 
ing-point numbers (at some expense of accuracy), can repre- 
sent real numbers within a much larger range. The range of a 
16-bit integer is -32768 to 32677, whereas an FFP format 
floating-point number can represent a real number in the 
range -9.22337177E18 to 9.22337177E8. 

The Amiga system programmers took better care of the 
requirements of C language programmers than those of ma- 
chine language programmers. They provided C language sup- 
port routines to convert ASCII character representations into 
the correct 32-bit floating-point number format, for instance, 
but the machine language routines were not provided. The 
MATH.ASM listing provided in this book includes ASCIITOFFP, 
a subroutine to convert ASCII to the Amiga 32-bit FFP (Fast 
Floating-Point) format, and HEXCONVERT, which prints out 
the HEXADECIMAL contents of the register DO to the CLI 
window. 

The illustration in Figure 32-1 shows the 32-bit fast 
floating-point format that can be used with both the MathFFP 
(simple arithmetic) library and the MathTrans library (the li- 
brary of transcendent functions, such as trigonometry, loga- 
rithms, and so on). The IEEEDOUBLE (double-precision, 64- 
bit) format is not covered here. Its use is restricted to the 
MathlEEEDoubBas library, which has only simple arithmetic 
capabilities. 
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Figure 22-1. 32-bit Fast Floating-Point (FTP) Number 
Representation 


U 


BIT BIT BIT BIT BIT 
31 23 IS 7 


U 
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MANTISSA ) EXPONENT 




SIGN 
BIT 

MANTISSA = $81 


u 


EXPONENT = 848 




VALUE = 1/2 





There are two additional requirements for this format: ev- 
ery number (except 0) has a 1 in the most significant (leftmost) 
bit when normalized, and the 7-bit exponent value is in- 
creased by $40 (again, except for the number 0). This format 
can reliably handle a real number of no more than seven dig- 
its, so there's some limitation of accuracy with 32-bit math. 
Use IEEE double-precision when more accuracy is needed. 

Table 22-1. shows some common floating-point numbers 
and their hexadecimal and binary representations in FFP 
format. 

Table 22-1. Conversion Equivalents Between ASCII Decimal and 
Fast Floating-Point Format 



Decimal 

0.000000 
1.000000 
2.000000 
4.000000 
10.000000 

100.000000 
3.14159 

-1.000000 



Hexadecimal 
00000000 

80000041 

80000042 

80000043 

A0000044 

C8000047 

C90FD042 

800000C1 



Binary 

00000000 

10000000 

10000000 

10000000 

10100000 

11001000 

11001001 

10000000 



00000000 
00000000 
00000000 
00000000 
00000000 
00000000 
00001111 
00000000 



00000000 
00000000 
00000000 
00000000 
00000000 
00000000 
11010000 
00000000 



00000000 
01000001 
01000010 
01000011 
01000100 
01000111 
01000010 
11000001 



Note that is treated in a special manner. It's a long word 
consisting of 32 zero bits. Also note that negation changes 
only the high bit of the bit in front of the exponent. Doubling 
an FFP format number simply means increasing its exponent 
by one. 
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The CLIFLOAT program in Listing 22-2 passes floating- 
point numbers to a program by way of the command line. The 
principles of the CLIECHO program are used to pick up the 
command tail, and the ASCIITOFFP subroutine is used to 
make a floating-point conversion, unless there's an error. Then 
HEXCONVERT is used to print the floating-point version of 
the number back to the CLI window. The MANDELBROT 
program also utilizes these routines to pass five different nu- 
meric parameters to the program. The same principles of num- 
ber handling can be used with a string gadget. Since a string 
gadget has a known buffer location, its address can be pro- 
vided to the ASCIITOFFP subroutine, and the buffer's numeri- 
cal contents (converted to FFP format) will appear in DO. 

Listing 22-1, MATH.ASM, is the last of the type-in in- 
clude files for this book. It has support routines for using the 
32-bit floating-point math routines in the MATHFFP library of 
the Amiga. Type in this file and save it as 

DEV:RAMIT/INCLUDES/MATH.ASM 

This file adds math support routines to the includes direc- 
tory on your DEV disk. 

Listing 22-1. MATH.ASM 

Support routines and macros for Amiga floating-point math. 

******************************** MATH.ASM BY DANIEL WOLF 

COPYRIGHT 1987 BY COMPUTEI BOOKS 

33/10/87 

LVO.SPFix EQU 5FPPPPPE2 

LVO.SPFlt EQU 5FFFPPPDC 

LVO.SPCmp EQU 5FFFPFFD6 

LVO.SPTst EQU 5FFFFFFD0 

LVO.SPAbs EQU $FFFFFFCA 

LVO.SPNeg EQU $FFFFFFC4 

LVO.SPAdd EQU SFFFPFFBE 

LVO.SPSub EQU SFFFFFFB8 

LVO.SPMul EQU 5PFPFFFB2 

LVO.SPDiv EQU 5PFFFFFAC 

LVO.SPSincos EQU SFFFFFFCA 

LVO.SPSin EQU $FFFFFFDC 

LVO.SPCos EQU ?FFFFFFD6 

LVO.SPTan EQU $FPPFFFD0 

LVO.SPAtan EQU $PFFPFFE2 

LVO.SPSqrt EQU SFFFFFFA0 

LVO.SPAcos EQU $FFPPPF88 

LVO.SPAsin EQU $FFPFFF8E 

IPND VLENW 
VLENW EQU 2 
ENDC 

;FFP MATH SUPPORT CODE 
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ASCIITOHEX 

fAl 
PUSHREG D1-D4/A2 
ZERO 00 
ZERO Dl 
ZERO D2 
ZERO D3 
HOVE.L A1.D4 
ADD.L #2,D4 
SUBA.L #4,A1 

FRONTHEX 
MOVE.B (A0)+,D0 
CMPI.B #' ',D0 
BEQ.S FRONTHEX 
CMPI.B #'0',D0 
BEQ.S FRONTHEX 
BRA FIRSTHDIG 

HEXINDIG 
MOVE.B (A0)+,D0 

FIRSTHDIG 
CMPI.B #'F',D0 
BHI.S NOTHEX 
CMPI.B #'A' ,D0 
BLT.S MAYBELOW 
SUBQ #7,00 
BRA HEXIT 

MAYBELOW 
CMPI.B #'0' ,D0 
BLT.S NOTHEX 
CMPI.B #'9',D0 
BHI.S NOTHEX 



HEXIT 

ADDQ #1,D3 

CMP.L MAXHEX,D3 

BEQ TOOMANYHEX 

ANDI.L #$F,D0 
ROTHEXIT 

MOVEQ #3,D2 
ROTINLOOP 

MOVE.L #VLENW-1,D1 

MOVE.L D4.A2 
ROTHEX 

ROXL.W -(A2) 

OBRA Dl, ROTHEX 

DBRA D2, ROTINLOOP 

OR.L D0,(A1) 

BRA HEXINDIG 
NOTHEX 

CMPI.B #' , " ,D0 

BEQ.S ENDHEXOK 

CMPI.B #' ' ,D0 

BEQ.S ENDHEXOK 

TST.B D0 

BEQ.S ENDHEXOK 
TOOMANYHEX 

MOVE.L #?FF,D0 

BRA ENDHEXIN 
ENDHEXOK 

PUSHREG D0 

ADDA.L #4,A1 

MOVE.L -(A1),D0 

BSR HEXCONVERT 

PULLREG D0 
ENDHEXIN 

PULLREG D1-D4/A2 

RTS 

ENDC 

IFD FFP 
ASCIITOFFP 

MOVEA.L _MATHBASE,A6 
LEADINGSPACE 

CMPI.B #' ' ,(A0) 

BNE.S CHEKNEG 



,- ROUTINE TAKES IN MAXHEX DIGITS OF HEX INTO ARRAY IN MEM 

;A0 POINTS TO ASCII 

POINTS TO LEAST SIGNIFICANT WORD OF HEX RESULT IN MEMORY 



u 
u 

LJ 
U 



; CHECK FOR TOO MANY INPUT DIGITS 

; ISOLATE THE HEX DIGIT 

;COUNT FOR FOUR SINGLE BIT ROTATES OF ALL WORDS IN V 

iAl POINTS TO L.S. WORD OF MEMORY ARRAY FOR VARIABLE 

! ROTATE BY 1 BIT FROM LSWORD TO MSWORD 

;IN THE ARRAY TOWARD THE L.S. WORD (UP IN ADDRESSES!) 

; ROTATE BACK FOR D3 WORDS - D4 BITS 

;-0R- IN THE NIBBLE DIGIT OBTAINED FROM ASCII 

;GET ANOTHER DIGIT 



;SAVE LAST CHARACTER FOUND 



;LAST CHARACTER 



u 
u 



;ENTER W/ A0 POINTING TO ASCII DECIMAL TEXT 



284 



u 
u 



n 
n 



Amiga Machine language Programming 



i i 

n 
n 



AODA.L #1,A0 
BRA.S LEADINGSPACE 

CHEKNEG 
MOVE. I, #0, NEGATIVE 
CMPI.B # , -',(A0) 
BNE.S POSITIVPART 
MOVE.L #128, NEGATIVE 
ADDA. I, tl,A0 

POSITIVPART 
MOVE.L #0,RITODP 
MOVE.L #0,LEFTODP 
MOVE.L #0,RDPDIGITS 
MOVE.L #0,LDPDIGITS 
MOVE.L #0,FLOATNUM 
MOVEQ.L #0,D4 
BSR DOPART 
TST.L Dl 

BNE CONVERTERROR 
MOVE.L D0.LEFTODP 
MOVE.L D2.LDPDIGITS 
CMPI.B #• .' ,(A0) 
BNE LEFTONLY 
AODA.L #1,A0 
MOVE.L #1,D4 
BSR DOPART 
TST.L Dl 

BNE CONVERTERROR 
MOVE.L D0.RITODP 
MOVE.L D2.RDPDIGITS 

PINILEPT 
MOVE.L LDPDIGITS.D7 
SUBQ.L #7,D7 
BLE.S FINIRIGHT 
MOVE.L LEFTODP.D0 
BEQ.S FINIRIGHT 
MOVE.L TEN.D2 

1$ 
JUST SPMul 
SUBQ.L #1,D7 
BNE.S 1$ 
MOVE.L D0.LEFTODP 

FINIRIGHT 
MOVE.L RDPDIGITS.D7 
BEQ.S FINISHCONV 
MOVE.L RITODP.D0 
BEQ.S FINISHCONV 
MOVE.L TEN.D1 

2? 
JUST SPDiv 
SUBQ.L #1,D7 
BNE.S 2$ 
MOVE.L D0.RITODP 

FINISHCONV 
MOVE.L RITODP.D0 
MOVE.L LEFTODP.D1 
JUST SPAdd 

LEFTONLY 
MOVEQ #0,D1 
MOVE.L NEGATIVE, D3 
EOR.L D3.D0 
MOVE.L D0.FLOATNUM 

CONVERTERROR 
RTS 

DOPART 

MOVE.L #0, INTEGER 

MOVEQ #0,D0 

MOVEQ #0,D1 

MOVEQ #0,D2 

MOVEQ #0,D3 

MOVEQ #0,D5 
LEADINGZERO 

MOVE.B (A0)+,D3 

CMPI.B #'0',D3 

BNE.S FIRSTDIGA 

TST.L D4 



;IS IT A NEGATIVE NUMBER? 



FIRST LEFT OF DP 

EXIT W/ FLOAT IN D0 AND FLOATNUM 

Dl INDICATES: OK 

NOT ERROR II 



;THEN RIGHT OF OP 



;} LEADING ZEROS 

; LEADING ZEROS DO COUNT RIGHT OF THE DPI I 



;ONLY ADD TO NUMDIGITS IF RIGHT OF DP 
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BEQ.S LEADINGZERO 
ADDQ.L #1,D5 
BRA.S LEADINGZERO 

PIRSTDIG 
MOVE.B (A0)+,D3 

PIRSTDIGA 
CMPI.B #"9',D3 
BHI.S NOMORDIGITS 
CMPI.B #'0',D3 
BLT.S NOMORDIGITS 
ANDI.L #$0P,D3 
LSL.L #1,D0 
MOVE.L D0.D1 
LSL.L #2,00 
ADD.L D1.D0 
ADD.L D3.O0 
ADDQ.L #1,D2 
CMPI.L #7,D2 
BNE.S FIRSTDIG 

MORDIGITS 
MOVE.B (A0)+,D3 
CMPI.B #'9',D3 
BHI.S NOMORDIGITS 
CMPI.B #'0',D3 
BLT.S NOMORDIGITS 
TST.L D4 
BNE.S MORDIGITS 
ADDQ.L #1,D2 
CMPI.L #18, D2 
BNE.S MORDIGITS 

TOOMANY 
MOVEQ #1,D1 
BRA AERROREXIT 



u 
u 



u 



u 
u 



; DON'T ADD TO # PLACES IP RIGHT OF DP 
;JUST MOVE THE ADDR PTR IN A0 ALONG TO 
;A NON-DIGIT 



;T00 MANY DIGITS ERROR 



NOMORDIGITS 

ADD.L D5.D2 

SUBA.L #1,A0 

MOVE.L D0, INTEGER 

TST.L D0 

BEQ PARTDONE 

MOVE.L #97,1)1 
3? 

SUBQ.L #1,D1 

ASL.L #1,D0 

BCC.S 3$ 

ROXR.L #1,D0 

ANDI.L #$FFFFFF00,D0 

EOR.L D1,D0 

PARTDONE 

MOVEQ #0,D1 
AERROREXIT 

RTS 

ENDC 

IFD HEX 
HEXCONVERT 

PUSHALL 

LEA.L HEXBUF.A2 

LEA.L HEXDIGITS.A1 

MOVEQ. L #0,D3 

MOVEQ. L #0,D2 
MORHEX 

ROL.L #4,D0 

MOVE.L D0.D1 

ANDI.L #SF,D1 

MOVE.B 0(A1,D1.W),D2 

MOVE.B D2,0(A2,D3.W) 

ADDQ.L #1,03 

CMPI.L #8,D3 

BNE.S MORHEX 

DOSPRINT STDOUT,#HEXBUF 

PULLALL 

RTS 

ENDC 



u 
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.*** DATA stuff *** 

IPD PPP 
LEFTODP DC.L « 
LDPDIGITS DC.L 
RITODP DC.L 
HDPDIGITS DC.L 
FLOATNUM DC.L 
INTEGER DC.L 
TEN DC.L SA0000044 
NEGATIVE DC.L 

ENDC 



;PP CONVERTED FIRST 8 DIGITS LEFT OP DP 
( TOTAL NUMBER OF DIGITS LEFT OF DP 
;PP CONVERTED FIRST 8 DIGITS RIGHT OP DP 
•TOTAL NUMBER OF DIGITS RIGHT OF DP 
.•FINISHED FLOATING POINT NUMBER 
(INTEGER PART OP ONE SIDE OF DP 
(DECIMAL VALUE OF TEN IN FFP NOTATION 
(NEGATIVE FLAG FOR INPUT NUMBER 



IPD HEX 
HEXBUF DC.B 65,65,65,65,65,65,65,65,10,0 
HEXDIGITS DC.B '0123456789ABCDEF' 
MAXHEX DC.L 

ENDC 

EVENPC 



The ASCIITOFFP subroutine. This routine in 
MATH.ASM accepts a series of byte locations provided by a 
pointer passed in address register AO. If the bytes are the 
ASCII characters for a floating-point number, they will be con- 
verted to a FFP format and returned in register DO. For ex- 
ample, the ASCII characters 3.14159 (pi) are converted to a 
long-word FFP number of 32 bits. 

It works this way: 

1. Set up a zero-value register to be the FFP number. 

2. Set LEFT OF DECIMAL POINT flag. 

3. Scan for and skip over any leading space characters (ASCII 
$32). 

4. If the first nonspace character is a minus sign, set 
NEGFLAG. 

5. Scan for and skip over any leading Os. 

6. For each ASCII digit, multiply existing FFP format number 
times ten, add appropriate new digit, and increase the 
LEFT digit count. If the number of digits exceeds seven, 
count the remaining digits and store in LEFT digit count. 

7. When decimal point is reached, store the LEFT OF DECI- 
MAL POINT integer obtained in step 6, and the LEFT digit 
count. Shift left the number obtained until the leftmost bit 
is a 1, counting the shifts necessary. Use the shift count to 
set the exponent portion of the number. 

8. Set RIGHT OF DECIMAL POINT flag. 

9. Scan for and count any leading Os (RIGHT digit count). 

10. Duplicate step 6, but for digits right of the decimal point. 

11. When a nonnumeric ASCII character (letter, space, comma, 
and so on) is reached, store the RIGHT OF DECIMAL 
POINT integer obtained in step 10, and the RIGHT digit 
count. Do the shift procedure outlined in step 7. 
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12. The LEFT OF DECIMAL POINT integer is an FFP-format 
number, as is the RIGHT OF DECIMAL POINT integer. 
The only remaining task is to modify them (the left num- 
ber may have had more than seven digits and the right 
number may have had leading digits as well as more than 
seven itself). 

13. If necessary, the left number is multiplied by ten, once for 
each digit in excess of seven. The right number always 
represents a number less than one, so it must be divided 
by ten, once for each of its digits that were counted. 

14. The result of step 13 is again two floating-point numbers, 
which, when they're added, represent the completely con- 
verted ASCII digit sequence. Adjustment of the sign fin- 
ishes the process. 

The ASCIITOFFP subroutine has an arbitrary upper limit 
of 18 digits on either side of the decimal point. It records an 
error in D4 if the process of conversion fails. It's intelligent 
enough to recognize integers (there need not be a decimal 
point at all). It doesn't recognize scientific notation, though. 
Here are some examples of legal input to the ASCIITOFFP 
routine: 



1.00 


303.000000456 


-1.05555 


-000000002.22222 


.00003333 


120 


000000033.33 


-10 



The HEXCON routine in MATH.ASM is assembled con- 
ditionally according to the three-letter HEX symbol. This rou- 
tine accepts any 32-bit number in DO and prints its 
hexadecimal form to the STDOUT file, using AmigaDOS. 

Listing 22-2 is the CLIFLOAT demonstration program. It 
allows you to type in floating-point numbers as part of a pro- 
gram's command line. It demonstrates ASCIITOFFP as well as 
HEXCON, and a few of the calls to library math routines. 

Listing 22-2. FPCMD.ASM 

Floating-point conversion and math demonstration. 

##;FPCMD.ASM BY DANIEL WOLF 

;COPYRIGHT 1987 BY COMPUTEI PUBLICATIONS 

;O9/I0/87 

BRA _START 

MAT EQU 1 
FFP EQU 1 

288 



u 
u 



u 



u 
u 



u 
u 



n 

n 

n 

n 
n 



Amiga Machine Language Programming 



HEX EQU 1 

WBC EQU 1 

INCLUDE "HEADER" 

MAIN 
DOSPRINT STDOUT,#MYMESSAGE 
TST.L ENDPROMWB 
BEQ FROMUSER 
LEA DEFAULTSTRING.A0 
BRA FIRSTPARAM 

FROMUSER 
MOVEA.L COMMAND, A0 
CMPI.B f?' AM) 
BEQ SHOWUSAGE 



!IF USER GAVE NO PARAMS, USE DEFAULTS 



FIRSTPARAM 
BSR ASCIITOFFP [TAKE FIRST COMMAND LINE PARAMETER 
TST.L Dl [CONVERT IT TO FP 

BNE BADARGS ;D1=0 MEANS NO ERROR IN CONVERSION 
MOVE.L D0.N1 (FP NUMBER IS IN D0 IF SUCCESSFUL 
BSR HEXCONVERT (SHOW US THE RESULTS 

CMPI.B #', ' , (A0)+ 
BNE BADARGS 
BSR ASCIITOFFP 
TST.L Dl 
BNE BADARGS 
MOVE.L D0.N2 
BSR HEXCONVERT 



(IS NEXT COMMAND LINE CHARACTER A COMMA? 
(NO, MEANS NO SECOND NUMBER SO QUIT 



CMPI.B #' , ' ,(A0)+ 

BNE NOMORE (NOPE, 

BSR ASCIITOFFP 

TST.L Dl 

BNE BADARGS 

MOVE.L D0.N3 

BSR HEXCONVERT 



(IS NEXT COMMAND LINE CHARACTER A COMMA7 
THERE WERE ONLY THE MINIMUM TWO NUMBERS 



(IF THERE WAS A THIRD NUMBER, 
(FOURTH OR ELSE QUIT 



) + 
(THE FIFTH NUMBER IS ENTIRELY OPTIONAL 



CMP.B #',',(A0)4 
BNE BADARGS 
BSR ASCIITOFFP 
TST.L Dl 
BNE BADARGS 
MOVE.L D0.N4 
BSR HEXCONVERT 

CMPI.B #' , ' , (A£ 
BNE NOMORE 
BSR ASCIITOFFP 
TST.L Dl 
BNE BADARGS 
MOVE.L D0.N5 
BSR HEXCONVERT 



NOMORE 
MOVE.L #TICKSPERSECOND,Dl,-WAIT ONE SECOND 
DOSLIB DELAY 

DOSPRINT STDOUT,#PRODUCT 
MULTIPLY(NOW TRY A COUPLE MATHFFP LIBRARY ROUTINES 
MOVE.L N1.D0 
MOVE.L N2.D1 

MATHLIB SPMul( MULTIPLY FIRST TWO NUMBERS 
BSR HEXCONVERT [SHOW THE RESULTS 

DOSPRINT STDOUT,#QUOTIENT 
DIVIDE 
MOVE.L N1,D0 
MOVE.L N2.D1 

MATHLIB SPDiV[ DIVIDE FIRST TWO NUMBERS 
BSR HEXCONVERT,' SHOW RESULTS 



THERE MUST BE A 
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DONE 
MOVE.L #TICKSPERSECOND,Dl;WAIT 4 SECONDS 
ADD.L D1.D1 
ADD.L D1.D1 
DOSLIB DELAY 

ZERO D0 
ERROR 

RTS 

BADARGS 
SHOWUSAGE 

DOSPRINT STDOUT,#0SAGE 

BRA DONE 

EVENPC 

;*** DATA DECLARATIONS *** 

Nl DC.L 
N2 DC.L 
N3 DC.L 
N4 DC.L 
N5 DC.L 

USAGE 
DC.B 10, 'usage : FPCMD £N1,N2[ ,N3,N4[,N5]]] ' ,10 
DC.B 10, 'sample: FPCMD -2.25,-1.5,3,3,16" , 10,0 
EVENPC 

DEFAULTSTRING 
DC.B '3. 14159, 2. 7182845, 1,10, 100', 0rPI, E, 1, 10, 100 - ALL 5 
EVENPC 

MYMESSAGE 
DC.B 10, 'FPCMD by Daniel Wolf Copyright 1987 by COMPUTEI PUBLICATIONS' ,10,0 
EVENPC 

PRODUCT 
DC.B 10, 'PRODUCT OF FIRST TWO NUMBERS = ',0 
EVENPC 

QUOTIENT 
DC.B 10, "QUOTIENT OF FIRST TWO NUMBERS = ' ,0 
EVENPC 
END 

Other Math Applications 

Once a number is in the FFP format for use with the MathFFP 
library, all the operations of a scientific calculator are available 
through the use of the MathTrans library. 

The FFP format is used by both the MathFFP and the 
MathTrans libraries. The STARTUP.ASM code opens the }__ ! 

MathTrans library if the TRA symbol is defined. Tables 22-2 
through 22-5 are lists of MathFFP and MathTrans library 
routines with specifications for passing parameters in the | j 

registers. 

As an exercise, you might like to try writing a routine 

complementary to ASCIITOFFP: one that converts a 32-bit | ] 

floating-point number back into ASCII characters. You might 
name such a routine FFPTOASCII. 

U 
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Table 22-2. MathFFP Library Routines 

Calling specifications for parameters in registers. The result is always in register 
DO. 

(Condition 
Codes){l} 
Name Description Registers N Z V 

SPFIX Convert floating point to integer DO s s s 

SPFLT Convert integer to floating point DO s s 

SPABS Absolute value of floating-point DO s 

number 

SPNEG Negative of floating-point number DO s s 

SPADD Add two floating-point numbers D0,D1 s s s 

SPSUB Subtract two floating-point numbers D0,D1 s s s 
SPMUL Multiply two floating-point numbers D0,D1 s s s 
SPDIV Divide two floating-point numbers D0,D1 s s s 

(D0/D1) 
SPCMP Compare two floating-point numbers D0,D1 s 
SPTST Test if floating-point number equals Dl s s 

zero 

{1} An S appearing under the N, V, or Z column means the flag will be set; a 
means it will be cleared. 

Table 22-3. Values Returned by SPCMP Library Function 

Value Meaning 

1 if DO > Dl (D0,D1 here refer to the input floating-point 
numbers) 
-1 ifD0<Dl 

if DO = Dl 

This function also leaves meaningful results in some additional con- 
dition codes of the MC68000: 

Result Meaning 

GT if DO > Dl (D0,D1 here refer to input floating-point 

numbers) 
GE if DO > = Dl 
EQ if DO = Dl 
NE if DO <> Dl 
LT if DO < Dl 

LE if DO < = Dl 
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Table 22-4. Values Returned by the SPTST Library Function 



Value 

1 

-1 





Meaning 

if DO > 
if DO < 
if DO = 



This function also leaves meaningful results in additional condition 
codes of the MC68000: 

Result Meaning 

EQ if DO = 
NE if DO <> 
PL if DO > = 
MI if DO < 

Table 22-5. MathTrans Library Routines 

Calling specifications for parameters in registers. The result is always in data 
register DO. 



N 







s 

s 

s 

s 



Z 
s 
s 
s 
s 
s 
s 
s 



V 





s 
s 

S{1} 



Name Description 

SPASIN Arcsine of floating-point number 
SPACOS Arccosine of floating-point number 
SPATAN Arctangent of floating-point number 
SPSIN Sine of floating-point number 
SPCOS Cosine of floating-point number 
SPTAN Tangent of floating-point number 
SPSINCOS Sine and cosine of floating-point 

number 
SPSINH Hyperbolic sine of floating-point 

number 
SPCOSH Hyperbolic cosine of floating-point 

number 
SPTANH Hyperbolic tangent of floating-point 

number 
SPEXP Exponential of floating-point number 
SPLOG Natural logarithm of floating-point 

number 
SPLOG10 Base 10 logarithm of floating-point 

number 
SPPOW Power of floating-point number 

SPSQRT Square root of floating-point number 
SPTIEEE Convert floating-point number to 

IEEE 
SPFIEEE Convert IEEE to floating-point 

number 

{1} In addition to the floating-point number in DO, this function is called with the 
pointer to a desired cosine result in Dl. When the function returns, the sine result is in 
DO and the cosine result is in the location pointed to by Dl (even though Dl isn't an ad- 
dress register). 



Registers 
DO 

DO 
DO 
DO 
DO 
DO 
D0,(D1) 

DO 

DO 

DO 

DO 
DO 

DO 



(DO, power; 
Dl, number) 
DO 
DO 

DO 



u 
u 
u 
u 
u 
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CHAPTER 23 

ASMINT 



If you've purchased the companion disk for this book, or if 
you've typed in Listing 23-1 (ASMINT.ASM), the ASMINT 
program can be invoked from the CLI by typing its name and 
pressing Return. ASMINT can also be invoked from the Work- 
bench by double-clicking in its icon. 

ASMINT 

ASMINT is a workbench interface for the assembler (called 
ASM on the disk) that turns your source code, includes, and 
macros into machine language for your Amiga to execute. The 
ASMINT screen is made up of several features, each of which 
is explained below: 

The string gadgets. Text is entered by way of string gad- 
gets. You will enter such things as source and object file 
names through string gadgets. To alter the contents of a string 
gadget, click in it and use the keyboard to modify the string to 
your satisfaction. Then, press Return. 

The string gadgets include: 

Source file. The default for the Source file string gadget is 
source, but you may click on this gadget and enter any legal 
filename (for instance, DEV:SOURCES/ASMINT.ASM). 

Object file. The default for this string gadget is object, but 
you may click here and set the name of your choice. 

Listing file. The default Listing file value shows NIL: (fol- 
lowed by a space) and then CON:0/0/640/200/ASM_WATCH- 
MEWORK. As it stands, the listing will go to the NIL: device 
(that is, it won't be listed) and assembly will be uneventful 
and quiet. If you'd like to watch the assembler work, click on 
the Listing file gadget and delete NIL: and the space that fol- 
lows it. The listing will be directed to an AmigaDOS window 
and you'll see the progress of assembly. 
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If you want an actual file, enter the disk drive, directory 1 i 

path and file name in the Listing file gadget. The assembly l ~-- 1 

will finish and a file will be written containing the listing. 

The Listing file is versatile because you can use 
AmigaDOS conventions like CON:, SER:, and PRT: to direct ' — ' 

listings anywhere "on the fly," or just use a conventional 
ramdisk file to receive the listing and print it later using the | 

List button. ^- J 

Include list. Here you may enter a list of directories of in- 
clude files for assembly or AUTOLINK. This string is automat- 
ically used with the -i flag of ASM68010. If you leave this 
string blank, the -i flag is ignored. For more information on 
the -i flag, see Appendix A. 

Edit file. Here you may enter the name of the file you 
want EMACS to read when you click the Edit button. If you 
leave this string gadget blank, EMACS will read whichever file 
you've named in the source file string gadget. 

Make file. You can put the name of an AmigaDOS COM- 
MAND file in the Make file string gadget. A COMMAND file 
is the type normally operated by using EXECUTE at the CLI. 

When you try to activate the Assemble or Autolink but- 
tons, the command file will be executed instead. This allows 
you to enter the name of a long and involved assemble, link, 
copy, and delete sequence set up in a preexisting command 
file, and the file will be executed, saving you from a great deal 
of typing. 

The buttons. To use a button, click on it once. Be careful 
to click only once because extra clicks are remembered. They 
will be executed when the Amiga completes the current task. 

Assemble. The Assemble button will cause ASM 
(ASM68010) to assemble the file specified in the source string 
gadget, to the file specified in the object string gadget. This 
creates the listing file, using the include list, if one is specified. 



If you've specified a make file, that file will be exe- 
cuted instead of ASM. 
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ASM produces a nonoperative object module that usually 
requires linkage to system libraries and support code (using 
the ALINK or BLINK linker programs) before it can be exe- 
cuted. ASM should reveal any syntax errors, undefined sym- 
bols, and other programming errors. 

Exec obj. The Exec obj button will activate your finished 
load module (Autolinked or linked using ALINK or BLINK). 
Load module is another name for an executable Amiga program. 

This button provides an AmigaDOS CLI-type working 
environment for the program. If you specified Autolink, you 
can also activate the program by double clicking in the Obj 
lightning bolt icon. 

List. The List button will first try to find the listing file. If 
it's found, it will ask you (using a requester) to choose 
whether to list to the screen or a printer. Make your choice. 
Another requester asks you to be sure you really want to list 
it. Listings can become quite long (easily 100K) if not managed 
well with NOLIST and LIST assembler directives surrounding 
uninteresting stretches of code. 

To cancel the printout, go offline with the printer using its 
online switch, or simply turn the printer off. It's recommended 
to list to the screen first, and list to printer only if you are sure 
the listing is of an appropriate length. 

Edit. The Edit button activates EMACS and reads in either 
the edit file (if there is one) or defaults to read the source file. 

New. The New button clears all the string gadgets, as well 
as the command buffer used internally by the program to acti- 
vate all the other programs (ASM, EMACS, RUN, and so on). 

Autolink. Autolink is a special flag feature of ASM68010 
(use the -a option, if you're working from the CLI). When you 
activate Autolink, your source file is both assembled and 
linked (if there are no errors). Normally, this is easy to do. If 
all symbols are defined within the source code, no further 
linking is required. To be sure all symbols are defined, provide 
yourself with comprehensive equate files that define all the 
symbols used in your programs (look them up in the manuals 
mentioned frequently in this text). 

The result of Autolink is that it produces an executable 
program, and Autolink makes a copy of the object file to Obj 
(the program that can be run by clicking in its icon). After 
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Autolink assembles and links your code, you can use the Exec | i 
obj button or the Obj icon to execute your program. 

If you want to use the Workbench Obj icon to invoke 
your finished program, be sure you have provided Workbench | | 
startup code in the program. See the STARTUP.ASM listing 
that provides the minimum requirements for either Work- 
bench- or CLI-based programs. Lj 

The menu. The menu provides an alternative to the but- 
tons. The menu supports both mouse and keyboard input. To 
enter a command key, enter the designated key in combina- 
tion with the right Amiga key. 

The only special thing to watch for when using the menu 
is that ASM and Autolink are combined on a single line. This 
prevents confusion when they're arranged closely in a menu 
format. Only one of them can be active, either ASM or Autolink. 

The ASM/ Autolink menu selection simply activates 
whichever was last used as a button. That is, if you first acti- 
vate the assembler function from the menu, it will use ASM 
(same as the Assemble button). If you've used the Autolink 
button, the menu will treat an ASM/ Autolink selection as if 
you clicked on the Autolink button. If neither the Assemble 
nor Autolink buttons have yet been used, the menu selection 
of ASM/ Autolink will default to Assemble. 

ASMINT is fun and makes machine language convenient, 
with minimum typing and (almost) no need for CLI expertise, 
thanks to Doug Leavitt for the -a (Autolink) option flag in his 
ASM68010. 



Listing 23-1. ASMINT.ASM 

,-NAME: ASMINT.ASM BY DANIEL WOLF 
; COPYRIGHT 1987 BY COMPUTE I PUBLICATIONS 
;09/10/87 



bra _START 




TXT equ 




RSQ equ 




WIN equ 1 




MEN equ 




GAD equ 




WBC equ 




include "HEADER 




RBPEN equ 


S0 


RFPEN equ 


51 


REQXMAX equ 


300 


REQYMAX equ 


65 



u 
u 



u 
u 
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; Project Menu Item Codes 

PROJ.TEST equ 507 FF 

PROJ. ABOUT equ $0000 

PROJ. NEW equ $0020 

PROJTASSEM equ $0040 

PROJ . EXECO equ $0060 

PROJ. PRINT equ $0080 

PROJ. EDIT equ $00 A0 

PROJ. QUIT equ $00C0 

OPENIT MACRO 
move.l #MODE_NEWFILE,d2 
DOSLIB OPEN 
move.l d0,ErrFD 
ENDM 

EXECUTIT MACRO 
bsr PRINTOUT 
move.l fExecBuf.dl 
ZERO d2 

move.l ErrFD,d3 
DOSLIB EXECUTE 
ENDM 

MAKOPY MACRO 

lea \l,a0 
lea.l \2,al 
STRCPY a0,al 
ENDM 

MAKCAT MACRO 

lea \l,a0 
lea.l \2,al 
STRCAT a0,al 
ENDM 

; Simple string copy macro 

; Usei STRCPy src.dest 

STRCPy MACRO 

RSTRCPy \1,\2,\@ 

ENDM 

RSTRCPY MACRO 
\3. 

move.b (\l)+,(\2)+ 

bne \3 

endm 

; Simple string append macro 
r Uset STRCAT src,dest 
STRCAT MACRO 

RSTRCAT \1,\2,\@ 

ENDM 

RSTRCAT MACRO 
\3: 

move.b (\2)+,d0 

bne \3 

subq.l #1,\2 

STRCPY \1.\2 

ENDM 

MAIN 

move .1 ap , STACK 

tst.l ENDFROMWB ; IF INITIATED FROM WB, THEN NO ANNOUNCEMENTS YETl 

bne.s _BUILDAWINDOW 
FROMUSER 

DOSPRINT STDOUT,#MyMESSAGE ;IF INITIATED FROM CLI, THEN OUTPUT TITLE MESSAGE 

ZERO d0 

movea.l COMMAND, a0 ;PUT ADDRESS OF COMMAND LINE IN A0 

cmpi.b S'?',(a0) ;IF FIRST CHARACTER IS ? THEN 

bne.s _BUILDAWINDOW 

bra USAGE ; PRINT OUT THE USAGE TEXT 
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_BUILDAWINDOW 
move. 1 #CLOSEWINDOWIMENUPICKIGADGETUP,_THISIDCMP 

move . 1 #ACTI VATE I WINDOWDRAG 1 WINDOWDEPTH I WINDOWCLOSE I SMART_REFRESH,_THISFLAGS 
MAKEWIN #ASMINTITLE, 40, 15, 500, 160, ERROR, WINDOW 

_BUILDMENU 

MITEMLIST MITEM0 , MITEM1 , MITEM2 , MITEM3 , MITEM4 , MITEM5 , MITEM6 ,0,6,150 

MAKEMEN MYCMDKEYS , MYMUEXES , ASMWMENUT ITLE , DONE 

move.l dl,_THISMENU ;MAKEAMENU RETURNS WITH POINTER TO MENU IN Dl 

move.w #5,d0 (LEFEDGE FOR THIS MENU 

move.w #120, dl fWIDTH FOR THIS MENU 

bsr CREATEMENU ;THIS CREATES THE ACTUAL MENU ATTACHED TO THE MITEMS 

MENUATTACH 

"move.l WINDOW, a0 i SUPPLY POINTER TO WINDOW IN A0 

move.l _THISMENU,al /SUPPLY POINTER TO MENU #0 IN Al 

INTLIB SETMENUSTRIP SAND ATTACH THE MENU TO THE WINDOW 

_BUILDASMGADGETS 
lea GTEXTl.al 
move.w #10, d4 
move.w #140, d5 
bsr MAKEAGADGET 
move.l d0,al 
move.l al,_FIRSTGADGET 
move.l WINDOW, a0 
bsr ADDNEWGADG 

NEWBGADG GTEXT2, 110, 140, WINDOW 
NEWBGADG. GTEXT3, 210, 140, WINDOW 
NEWBGADG GTEXT4, 270, 140, WINDOW 
NEWBGADG GTEXT5 , 330 , 140, WINDOW 
NEWBGADG GTEXT6, 390, 140, WINDOW 

NEWSGADG SGBUF1.UBUF, 10, 20, WINDOW 

NEWSGADG SGBUF2,UBUF, 10, 40, WINDOW 

NEWSGADG SGBUF3.UBUF, 10, 60, WINDOW 

NEWSGADG SGBUF4,UBUF, 10, 80, WINDOW 

NEWSGADG SGBUF5.UBUF, 10, 100, WINDOW 

NEWSGADG SGBUF6 , UBUF ,10,120, WINDOW 

PRINTNEWAT WINDOW, MSG1 ,330,20, ERROR 
PRINTNEWAT WINDOW, MSG2 , 330 , 40 , ERROR 
PRINTNEWAT WINDOW, MSG3 ,330,60, ERROR 
PRINTNEWAT WINDOW, MSG4 , 330 , 80 , ERROR 
PRINTNEWAT WINDOW , MSG5 , 330 , 100 , ERROR 
PRINTNEWAT WINDOW, MSG6 , 330 , 1 20 , ERROR 

move.l __FIRSTGADGET,a0 
move.l WINDOW, al 
INTLIB REFRESHGADGETS 

MAKEREQ NOPrtVerb,R_PosVerb, R_NegVerb, ERROR 

SAVEREQ REQ1 

MAKEREQ NOLstVerb.R Pos Verb, R_NegVerb, ERROR 

SAVEREQ REQ2 

MAKEREQ NoErrWVerb, R_PosVerb, R_NegVerb, ERROR 

SAVEREQ REQ3 

MAKEREQ DoneErrWVerb , , R_ContVerb , ERROR 

SAVEREQ REQ4 

MAKEREQ NoExecWVerb, R_PosVerb, R_NegVerb, ERROR 

SAVEREQ REQ5 

MAKEREQ DoneExeowVerb,0,R ContVerb, ERROR 

SAVEREQ REQ6 

MAKEREQ About Verb, 0,R ContVerb, ERROR 

SAVEREQ REQ7 ~ 

MAKEREQ ListVerb , Prt Verb , ScrnVerb , ERROR 

SAVEREQ REQ8 

MAKEREQ ListRVerb.R ContVerb, R_NegVerb, ERROR 

SAVEREQ REQ9 

LOOP 
move.l WINDOW, a0 

move.l #?FFFF,d0 rWAKE UP THE WHOLE MENU NOW 

INTLIB ONMENU 
move.l WINDOW, a0 

move.l WW.USERPORT(a0),a0 (LISTEN TO PORT ATTACHED TO THIS WINDOW 
SYSLIB WAITPORT (WAIT FOR A SPECIFIED MESSAGE TO ARRIVE 



u 
u 
u 
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move.l WINDOW, a0 

move.l WW.USERPORT(a0),a0 

SYSLIB GETMSG 

tst.l d0 

beq LOOP 

move.l d0,a0 
move.l IH. CLASS (a0),d7 
move.w IM.CODE(a0),d6 
move.w IM.MOUSEX(a0),d5 
move.w IM.MOUSEY(a0) ,d4 
move.l a0,al 
SYSLIB REPLYMSG 
cmp.l #CLOSEWIND0W,d7 
beq DONE 

cmp.l #MENUPICK,d7 

bne chkgadget 

cmp.w #MENUNULL,d6 

beq LOOP 

and.w #PROJ.TEST,d6 

cmp.w #PROJ.QUIT,d6 

beq DONE 

cmp.w #PROJ. ABOUT, d6 

bne chknew 

jsr pro j about 

bra LOOP 
chknew : 

cmp.w #PROJ.NEW,d6 

bne chkprint 

jsr projnew 

bra LOOP 
chkprint : 

cmp.w #PROJ. PRINT, d6 

bne chkassem 

jsr projprint 

bra LOOP 
chkassem: 

cmp.w #PROJ.ASSEM,d6 

bne chkexecobj 

jsr projassem 

bra LOOP 
chkexecobj : 

cmp.w #PROJ.EXECO,d6 

bne chekedit 

jsr projexecobj 

bra LOOP 
chekedit: 

cmp.w #PROJ.EDIT,d6 

bne LOOP 

jsr projedit 

bra LOOP 



;MESSAGE HAS ARRIVE WITHIN SPECIFICATIONS 
{POINTER TO INTUIMESSAGE COMES BACK IN D0 
j NO MESSAGE THERE, SO LOOP 



,»*** CHECK FOR MENU OPTIONS 

; Not a Menu pick. Check gadgets 

; Ignore 



chkgadget: 

cmp.l #GADGETUP,d7 

bne LOOP 

cmp.w #140, d4 

ble LOOP 
dogadgl : 

cmp.w #110, dS 

bge dogadg2 

jsr projasseml 

bra LOOP 
dogadg2 

cmp.w #210, d5 

bge dogadg3 

jsr projexecobj 

bra LOOP 
dogadg3: 

cmp.w #270, d5 

bge dogadg6 

jsr projprint 

bra LOOP 



.*«** CHECK FOR GADGET information 

; Not a gadget, ignore 

;cant be a Boolean gadget, Y is too low 
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dogadg6 1 

cmp.w #330, d5 

bge dogadgV 

jsr projedit 

bra LOOP 
dogadg? : 

cmp.w #390, d5 

bge dogadg8 

jsr pro j new 

bra LOOP 
dogadg8 

jsr projauto 

bra LOOP 

.**** SUBROUTINES 

pro j about t 
REQUEST WINDOW, REQ7 
rts 

projedit: 

MAKOPY CDSTRING.ExecBuf 

MAKCAT EMACSTRING.ExecBuf 

tst.b SGBUP5 

beq defeditstr 

MAKCAT SGBUF5 , ExecBuf 

bra projednow 
defeditstr i 

MAKCAT SGBUF1, ExecBuf 

projednow: 

move.l #Edout,dl 

OPENIT 

bne projed2 

REQUEST WINDOW, REQ3 

tst.l d0 

bne projednow 

rts 



u 
u 
u 
u 
u 



;Tells user what asm/asi are 



;IS THERE A SEPARATE EDIT FILE? 



;no, just assume same as assembly source 
;**** OPEN an output file for error messages 



RETRY 
ABORT 



,**** Trv to execute the assembler curse if it fails 
projed2: 
EXECUTIT 
move.l ErrFD,dl 
DOSLIB CLOSE 
rts 

projauto 
move.w #l,Absflag 
bra projassem 

pro j new: 

PUSHREG a2-a6 

moveq #(STRSIZ/2)-l,d0 

lea.l SGBUFl,a0 

lea.l SGBUF2,al 

lea.l SGBUF3,a2 

lea SGBUF4,a3 

lea SGBUF5,a4 

lea SGBUF6,a5 

lea UBUF,a6 

moveq #0,dl 
1?: 

move.w dl,(a0)+ ; Clear Ibufl 

move.w dl,(al)+ t clear Ibuf2 

move.w dl,(a2)+ ; Clear Ibuf3 

move.w dl,(a3)+ , clear Ibuf4 

move.w dl,(a4)+ ; clear Ibuf5 

move.w d.l,(a5)+ ; clear Ibuf6 

move.w dl,(a6)+ ; Clear Ubuf 

dbf d0, 1? 

move.l FIRSTGADGET,a0 

move.l WINDOW, al 

ZERA a2 

INTLIB REFRESHGADGETS 

PULLREG a2-a6 

rts 



u 

D 

u 
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projprinti 

prtli 
MAKOPY DSTRING,ExecBuf 
MAKCAT SGB0P3,ExecBuf 
move.l #ExecBuf,dl 
move.l #MODE_OLDFILE,d2 
DOSLIB OPED 
move.l d0,LstFD 
bne prt2 

REQUEST WINDOW, REQ2 
tst.l d0 
bne prtl 
bra prt6 

prt2i 

REQUEST WINDOW, REQ8 

tst.l d0 

bne prtoprt 

bra prtocon 
prtoprt : 

move.l #Prtstr,dl 

bra prt22 
prtocon t 

move.l #Constr,dl 
prt22i 

move.l #MODE_OLDFILE,d2 

DOSLIB OPEN 

move.l d0,PrtFD 

bne prt3 

REQUEST WINDOW, REQ1 

tst.l d0 

bne prt2 

bra prt5 

prt3: 
REQUEST WINDOW, REQ9 
tst.l d0 
beq prt4 

prt33: 
move.l LstFD,dl 
move.l fExecBuf,d2 
move.l #512, d3 
DOSLIB READ 
tst.l d0 
ble prt4 
move.l PrtFD,dl 
move.l #ExecBuf,d2 
move.l d0,d3 
move.l d3,d6 
DOSLIB WRITE 
cmp d6 , d0 
bne prt4 
bra prt33 

prt4: 

move.l PrtFD,dl 

DOSLIB CLOSE 
prt5: 

move.l LstFD,dl 

DOSLIB CLOSE 
prt6: 

rts 

projasseml: 

move.w #0, Aba flag 
projassem: 

tst.b SGBUF6 

beq proj0 
pro jmake : 

MAKOPY CDSTRING.ExeoBuf 

MAKCAT EXECSTRING.ExecBuf 

MAKCAT SGBUFG.ExecBuf 

bra proj4 



;Prlnt listing file if it exists 
.**** Try to open the listing file 



jfile not found 



f RETRY 
J ABORT 



; choose printer or screen 



;OPEN the printer 



I or console 



;not successful on OPEN 



RETRY 
ABORT 



; REALLY PRINT THE WHOLE THING? 

;user clicked ABORT 

;user clicked CONTINUE, so 

; Print the listing file 



. «*** CLOSE everything and exit 



;got here via ASSEM gadget, so just ASSEM1 
; Start a new assembly with the latest params 
;do ASM or ASM -a depending on how got here 
;check for MAKE file 
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proj0: 

MAKOPY CDSTRING.ExecBuf 

MAKCAT Asmstr, ExecBuf 
defasmdirt 

tst.w Absflag 

beq projl 

MAKCAT Absstr.ExecBuf 
projl: 

MAKCAT SGBUF1 , ExecBuf 

tst.b SGBUF2 

beq proj2 

MAKCAT Ob jstr, ExecBuf 

MAKCAT SGBUF2, ExecBuf 
proj2i 

tst.b SGBUF3 

beq proj3 

makcat Listingstr, ExecBuf 

MAKCAT SGBUF3,ExecBuf 
proj3: 

tst.b SGBUF4 

beq proj4 

MAKCAT Inclstrl, ExecBuf 

MAKCAT SGBUF4,ExecBuf 

MAKCAT Inclstr2,ExecBuf 

proj4: 

move.l #Errout,dl 

OPENIT 

bne proj5 

REQUEST WINDOW, REQ3 

tst.l d0 

bne proj4 

rts 



I no MAKE file 

;put default dir in execbuf 

(Check for AUTOLINK origin 



Source file string gadget 

Object file string gadget exists? 



Use Listing file if it exists 



; Add Include list if it exists 



OPEN an output file for error messages 



; RETRY 
; ABORT 



proj5s 

EXECUTIT 



;**** Try to execute the assembler curse if it fails 



I put code to COPY OBJECT PROGRAM a pre-existing DtPRG icon here 
tst.w Absflag 

beq AFTERCOPY 
MAKOPY CDSTRING.ExecBuf 
MAKCAT IC0NSTRING1, ExecBuf 
MAKCAT SGBUF2,ExecBuf 
MAKCAT ICONSTRING2,ExecBuf 
EXECUTIT 
AFTERCOPY! 
REQUEST WINDOW, REQ4 
move.l ErrFD.dl 
DOSLIB CLOSE 
rts 



projexecobj : 
MAKOPY CDSTRING.ExecBuf 
MAKCAT SGBUF2,ExecBuf 



(EXECUTE the object program 



proje2t 

move.l #Execout,dl 
OPENIT 

bne pro j el 

REQUEST WINDOW, REQ5 

tst.l d0 

bne proje2 

rts 



.**** OPEN an output file for error messages 



pro jel : 
EXECUTIT 

REQUEST WINDOW, REQ6 
move.l ErrFD,dl 
DOSLIB CLOSE 
rts 



. RETRY 
; ABORT 

.**** T r y to execute obj code curse if it fails 
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DONE 

move.l WINDOW, d0 

tst.l <S0 

beq.s DONE ALL 

move.l d0,a0 

INTLIB CLEARMENUSTRIP 
DONEALL 

ZERO d0 
QUIT 

move.l STACK, sp 

move.l d0,-(sp) 

move.l WINDOW, 30 

beq.s 1$ 

move.l d0,a0 

INTLIB CLOSEWINDOW 
15 

move.l (sp)+,d0 

rts 
QUITNOW 

move . 1 STACK , sp 

rts 

ERROR 
DOSPRINT STDOUT, SERRORTEXT 
moveq #CANTOPENWINDOW,d0 
bra QUITNOW 

USAGE 
DOSPRINT STDOUT, KUSAGETEXT 
ZERO d0 
bra QUITNOW 

PRINTOUT 
DOSPRINT ErrFD,#ExecBuf 
DOSPRINT ErrFD,#LINE 
rts 



EVENPC 

STACK del 
WINDOW del 

REQ1 del 0,0,0 

REQ2 del 0,0,0 

REQ3 del 0,0,0 

REQ4 del 0,0,0 

REQ5 del 0,0,0 

REQ6 del 0,0,0 

REQ7 del 0,0,0 

REQ8 del 0,0,0 

REQ9 del 0,0,0 

_FIRSTGADGET 
del 

JTHISMENU 
del 

ErrFD: 

del 
PrtFD: 

del 
LstFD: 

del 
Absflagt 

dew 1 
JTHISFONTHITE 
"dew 9 

SGBUF1 

deb 'Source' 

dcb.b 74,0 

EVENPC 
SGBUF2 

deb 'Object' 

dcb.b 74,0 
SGBUF3 

dcb.b 80,0 



;PTR TO BODY ITEXT, POSITEXT, NEGITEXT 



; POINTER TO TOP OF GADGET LIST 
J POINTER TO TOP OP MENU LIST 



; Generate ABS code by default 



.■STRING GADGET BUFFERS 
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SGBUF4 

dcb.b 80,0 
SGB0P5 

dcb.b 80,0 
SGBUF6 

dcb.b 80,0 
UBUF ; UNIVERSAL STRING GADGET UNDOBUFFER 

dcb.b 80,0 

ExecBuf t 
dcb.b 512,0 ; EXECUTE command buffer 

EVENPC 

ASMINTITLE 

dc.b ' Asmlnt by D. Wolf ',0 

EVENPC 
USAGETEXT 

dc.b 'Usage: asraint ' , 10 , 

EVENPC 
ERRORTEXT 

dc.b 10,' Sorry, cannot open window ',10,0 

EVENPC 
MYMESSAGE 

dc.b 10, 'Asmlnt by Daniel Wolf Copyright 1988 by Computet Publications' , 10, 

EVENPC 

GTEXT1 ; GADGET TEXTS 

dc.b ' ASSEMBLE ' ,0 

EVENPC 
GTEXT2 

dc.b ' EXEC OBJ ',0 

EVENPC 
GTEXT3 

dc.b ' LIST ',0 

EVENPC 
GTEXT4 

dc.b ' EDIT ',0 

EVENPC 
GTEXT5 

dc.b ' NEW ',0 

EVENPC 
GTEXT6 

dc.b ' AUTOLINK ',0 

EVENPC 

ASMWMENUTITLE 

dc.b ' Asmlnt ',0 

EVENPC 
MITEM0 

do .b ' ABOUT ' , 

EVENPC 
MITEM1 

dc.b ' NEW ',0 

EVENPC 
MITEM2 

dc.b ' ASM/ AUTO ",0 

EVENPC 
MITEM3 

dc.b ' EXECUTE ',0 

EVENPC 
MITEM4 

dc.b ' LIST ',0 

EVENPC 
MITEM5 

dc.b ' EDIT ',0 

EVENPC 
MITEM6 

dc.b ' QUIT ',0 

EVENPC 
MYCMDKEYS 

dc.b 'WNAXLEQ' 

EVENPC 
MYMUEXES 

del 57E,57D,57B,S77,56F,$5F,$3F 

MSG1 
dc.b ' Source File ',0 
EVENPC 



u 

LJ 
U 
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MSG2 

dc.b ' Object File ',0 

EVENPC 
MS63 

dc.b ' Listing File ' .0 

EVENPC 
MSG4 

dc.b ' Include List ' ,0 

EVENPC 
MSG5 

dc.b • Edit File ' ,0 

EVENPC 
MSG6 

dc.b ' MAKE File ' ,0 

EVENPC 

DAsmstr: 

dc.b 'dfl:',0 

EVENPC 
Asmstr: 

dc.b 'asm ',0 

EVENPC 
Absstr: 

dc.b '-a ' , 

EVENPC 
Objstr: 

dc.b ' -o ' , 

EVENPC 
Listingstr: 

dc.b ' -1 ' ,0 

EVENPC 
Inclstrl: 

dc.b ' -i "' ,0 

EVENPC 
Xnclstr2x 

dc.b "" ,0 

EVENPC 
Edout : 

dc.b 'CON:0/60/400/100/Asra(1.8) EDIT Window ',0 

EVENPC 
Er rout : 

dc.b 'CON:0/2S/640/150/Asm(1.8) ASM Window ',0 

EVENPC 
Execout: 

dc.b 'CON:0/60/640/120/Asm(1.8) EXEC Window ',0 

EVENPC 
Constr: 

dc.b 'CON:0/0/640/200/Asm(1.8) LIST Window ',0 

EVENPC 
Prtstr: 

dc.b 'PRT:',0 

EVENPC 
EXECSTRING 

dc.b "EXECUTE ',0 

EVENPC 
EMACSTRING 

dc.b 'EMACS ',0 

EVENPC 

;**** REQUESTERS **** POSITIVE/NEGATIVE responses 

R_PosVerb: 

dc.b 'RETRY' ,0 

EVENPC 
R_NegVerbi 

dc.b 'ABORT', 

EVENPC 
R_ContVerb: 

dc.b ' CONTINUE', 

EVENPC 
ScrnVerb : 

dc.b 'SCREEN', 

EVENPC 
PrtVerbs 

dc.b 'PRINTER', 

EVENPC 
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;**** REQUESTER BODY MESSAGES 

NoAsmVerb : 

dc.b 'Cannot Find Asm' ,0 

EVENPC 
NoExecWVerb : 
NoErrWVerb: 

dc.b 'Cannot OPEN Message Window' ,0 

EVENPC 
DoneExecWVerb : 
DoneErrWVerb: 

dc.b 'Done With Message window?', 

EVENPC 
NOPrtVerb: 

dc.b 'Cannot OPEN Output Device ',0 

EVENPC 
NOLstVerb: 

dc.b 'Cannot OPEN Listing File',0 

EVENPC 

AboutVerb: 

dc.b 'Asm Interface by Daniel Wolf',0 

EVENPC 
ListVerb: 

dc.b 'List To Screen or Printer ?',0 

EVENPC 
ListRVerb: 

dc.b 'List REALLY ??',0 

EVENPC 
CDSTRING: 

dc.b 'C:CD D: ' ,10, 'CD' ,10,0 

EVENPC 
DSTRING: 

dc.b 'D:',0 

EVENPC 
LINE: 

dc.b 13,10,10,0 

EVENPC 
IC0NSTRING1 : 

dc.b 'COPY ' 

EVENPC 
IC0NSTRING2 

dc.b ' to Obj' 

EVENPC 

END 



u 
u 
u 



POLYFRACASM 

POLYFRAC.ASM is a demonstration of fractal line drawing 

using the graphics library. POLYFRAC draws five different 

line fractals, including the dragon sweep, Hilbert curve, and 

three kinds of fractal trees. The menu selection has alternate .-■ - ( 

command keys and mutual exclude provisions. [__J 

When the program begins, it opens a window and draws 
the dragon sweep curve first. Each curve is drawn in several ,- , 

levels of detail and remains static in the window. This pro- [_^J 

gram demonstrates the speed and efficiency of machine lan- 
guage graphics programming on the Amiga. In the tree 
fractals, the Amiga produces many lines per second. [__J 

An interesting feature of the window used in 
POLYFRAC.ASM is its automatic adaptation to an interlaced 
screen. The interlace (400-line) screen can be activated [ ( 

through the Preferences program on the Workbench disk. 
When the window is opened, a check is made of the mode of 
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the screen. If interlace is the chosen mode, then the 
SIZEWINDOW Intuition function is used to double the win- 
dow's height. The window adapts automatically to the screen 
height. 

The code for this program is a good example of combining 
a window, menu, and graphics features into one application. 

Listing 23-2. POLYFRAC.ASM 

tPOLYFRAC.ASM by Daniel Wolf 

;COPYRIGHT 1988 BY COMPUTE! PUBLICATIONS 
J09/10/87 

bra _START 

GFX equ 1 
MAT equ 1 
TRA equ 1 

MEM equ 1 
WIN equ 1 
TXT equ 1 
FFP equ 1 

include "HEADER" 

MAIN 

move.l SP, STACK 

tst.l ENDFROMWB 

bne.s MENUWINDOW 
FROMUSER 

DOSPRINT STDOUT,#MYMESSAGE 

ZERO D0 
MENUWINDOW 

MAKEWIN #DRAGTITLE,40,4, 522, 195, ERROR 

move.l D0, WINDOW 

move.l WINDOW, A0 
move.l WW.RPORT(A0),RP 
INTLIB VIEWPORTADDRESS 
move.l D0,A2 
move.w VP. MODES (A2),D0 
and.w #LACE,D0 
tst.w D0 

beq.s FRACLACESET 
move.l #1,MYLACE 
ZERO D0 
move.l »;.95,D1 
move.l WINDOW, A0 
INTLIB SIZEWINDOW 
FRACLACESET 
MITEMLIST ITEM0, ITEM1, ITEM2, ITEM3, ITEM4, ITEM5,0,0, 5 
MAKEMEN MYCMDKEYS , MYMUEXES , MYMENUTITLE , ERROR 

move.l D1,_THISMENU 
move.w #5,D0 
move.w $120, DJ. 
bsr CREATEMENU 

MENUATTACH 
"move.l WINDOW, A0 
move.l _THISMENU,A1 
INTLIB SETMENUSTRIP 

move.l #TICKSPERSECOMD/2,Dl 
DOSLIB DELAY 

bsr DRAGONDRAW 
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LOOP 
move.l WINDOW, A0 
move.l #$FFFF,D0 
INTLIB ONMENU 
move.l WINDOW, A0 
move.l WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
move.l WINDOW, A0 
move.l WW.USERPORT(A0),A0 
SYSLIB OETMSG 
tst.l D0 
beq MYTIME 
move.l D0,A1 
move.l IM.CLASS(A3. ),D2 
move.w IM.C0DE(A1),D3 
move.w IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 

cmp.l tCLOSEWINDOW, D2 

beq DONE 

cmp.l #MENUPICK,D2 

bno MYTIME 

ZERO D0 

move.w D3,D0 

bsr MENUEVENT 

cmpi.w #5,D). 

beq DONE 
CHKDRAGON 

cmpi.w #0,D1 

bne.s CHKHILBERT 

move.l WINDOW, A0 

bsr _CLEARWINDOW 

bsr DRAGONDRAW 

bra MYTIME 
CHKHILBERT 

cmpi.w #1,D1 

bne.s CHKTTREE 

move.l WINDOW, A0 

bsr _CLEARWINDOW 

bsr HILBERTDRAW 

bra MYTIME 
CHKTTREE 

move.l #255,FIRSTX 

move.l #128,FIRSTY 

cmpi.w #2,D1 ;TRI 

bne.s CHKFTREE 

move.l «3,NANGLES 
NOWTREE 

move.l WINDOW, A0 

bsr _CLEARWINDOW 

bsr FRACBRANCH 

bra MYTIME 
CHKFTREE 

move.l #100,FIRSTY 

cmpi.w #3,D1 ;QUAD 

bne.s CHKFITREE 

move.l #4,NANGLES 

bra.s NOWTREE 
CHKFITREE 

cmpi.w #4,D1 ;QUINT 

bne MYTIME 

move.l #5,NANGLES 

bra.s NOWTREE 

MYTIME 
bra LOOP 

DONE 

move.l WINDOW, A0 

INTLIB CLEARMENUSTRIP 
DONEALL 

ZERO 00 
QUIT 

move.l STACK, SP 

move.l D0,-{SP) 

move.l WINDOW, D0 

beq.s 1$ 

move.l D0,A0 



Li 

LJ 
LJ 
U 

u 
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INTLIB CLOSEWINDOW 
15 

move. I (SP)+,D0 

rte 
QUITNOW 

move.l STACK, SP 

rts 

ERROR 
DOSPRINT STDOUT, #ERRORTEXT 
moveq #2j. ,D0 
bra QUITNOW 

FRACBRANCH 
PUSHALL 

move.w #l,LEVELO 
move.l #7,LOGLEN 
tst.l MYLACE 
beq.s BRANCHCONST 
move.l #8,LOGLEN 

BRANCHCONST 

move.l FIRSTX, D0 

MATHLIB SPPlt 

move.l D0.XOFP 

move.l FIRSTY.D0 

tst.l MYLACE 

beq.s NOLACETREE 

asl.l #1,D0 

move.l D0.FIRSTY 
NOLACETREE 

JUST SPFlt 

move.l D0,YOFP 

move.l NANGLES.D7 
move.l D7,D0 
JUST SPFlt 
move.l D0.D1 
move . 1 TWOP I , D0 
JUST SPDiv 
move.l D0.PHWHOLE 
move.l TWOFP.D1 
JUST SPDiv 
move.l D0,PHOVER2 
move.l PIOVER2.D1 
JUST SPAdd 

move.l D0,STARTANGLE 
move.l D0, ANGLE 
lea ANGLEARAY.A3 
move.l D0,(A3)+ 
move.l PHWHOLE.D1 
ADDANOTHERANGLE 
JUST SPAdd 
move.l D0, (A3)+ 
SUBQ.L #1,D7 
tst.l D7 
bne.s ADDANOTHERANGLE 

BRANCHDRAW 

move.l WINDOW, A0 

move.l #$FFFF,D0 

INTLIB OFFMENU 
BRANCHDR 

tst.l MYLACE 

bne.s LEVISSEVEN 

cmpi.w #7,LEVEL0 

beq DONEBRANCH 
LEVISSEVEN 

cmpi.w #8,LEVEL0 

beq DONEBRANCH 

move.l XOFP.CURXFP 

move.l YOFP.CURYFP 

move.l WINDOW, A0 

bsr CLEARWINDOW 

SETAPEN RP,#0 

RECTFILL RP,#185,#1,#330,#20 

SETAPEN RP,#1 
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ONEBRANCH 
move.l STARTANGLE, ANGLE 

lea NARAY.A4 
lea XINCARAY.A2 
lea YINCARAY.A3 

move . w LEVELO , D0 

asl.w #1,D0 

move*w D0, LEVEL 

bar DRAWB 

move.l #TICKSPERSECOND,Dl 

DOSLIB DELAY 

addi.w #1, LEVELO 

bra BRANCHDR 

DRAWB 

subi.l #l,LOGLEN 

subl.w #2, LEVEL 

move.w LEVEL. 00 

olr.w 0(A4,D0.W) 
DDRAWB 

addi.w #1,0(A4,D0.W) 

bsr SUBDRAWB 

move.w LEVEL. D0 

move.w 0(A4,D0.W),D). 

move.l MANGLES, D2 

cmp.w D2,D1 

bne.s DDRAWB 
WINDUPB 

addi.w #2, LEVEL 

add 1.1 n.LOGLEN 

rts 

SUBDRAWB 

move.l LOGLEN , D4 

movea.l _MATHTRANSBASE, A6 

move.l ANGLE, D0 

move.l #C0SANGLE,D1 

JUST SPSlncos 

add.l D4,D0 

move.l COS ANGLE, D6 

add.l D4.D6 

tst.l MYLACE 

bne.s NOXDOUBLE 

addq.l #1,D6 
NOXDOUBLE 

move . w LEVEL , D2 

asl.w #1,D2 

move.l D0,0(A3,D2.W) 

move.l D6,0(A2,D2.W) 

move.l CURYFP,D3. 

MATHLIB SPAdd 

move.l D0.NEWYPP 

JUST SPFix 

move.w D0,D3 ?NEWY 

move.l D6.D0 

move.l CURXPP.DJ. 

JUST SPAdd 

move.l D0.NEWXFP 

JUST SPFix 

move.w D0.D2 ;NEWX 
CONVERTPOINTS 

move.l CURYFP.D0 

JUST SPFix 

move.w DO, 1)4 fCURY 

move.l CURXFP.D0 

JUST SPFix 

move.w D4,D). 

DRAWLINE RP 

move.l NEWXFP.CURXFP 

move.l NEWYFP.CURYFP 

tst.w LEVEL 

beq.s NEWXNEWY 

bsr DRAWB 



,LEVEL=2*LEVEL0 TO POINT TO WORDS IN ARRAYS 



LEVEL=LEVEL-1 

N( LEVEL )=0 

N ( LEVEL ) =N ( LEVEL ) + 1 



MULTIPLY LENFP*SINANGLE=D0 



; DOUBLE XINC IF NOT INTERLACED 



; NEWYFP=CURYFP+YINC ( LEVEL ) 



; NEWXFP=CURXFP+XINC ( LEVEL ) 
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NEWXNEWY 
move.w LEVEL, D2 
asl.w #1,D2 
move.l 0(A2,D2.W),D1 
move.l CURXFP,D0 
MATHLIB SPSub 
move.l D0.CURXFP 
move.l 0(A3,D2.W),D1 
move.l CURYFP.D0 
JUST SPSub 
move.l D0.CURYFP 
add.w #1, ANGLENUM 
move . w ANGLENUM, 00 
move.l NANGLES.D). 
cmp.w DI,D0 
bne.s NEXTANGLE 
moveq.l #0,D0 
move.w D0, ANGLENUM 

NEXTANGLE 
asl.w #2,D0 
lea ANGLEARAY.A5 
move.l 0(A5,D0.W),D1 
move.l Dl, ANGLE 
rts 

DONEBRANCH 
PULLALL 
rts 

STARTANGLE del 
FIRSTX del 250 

FIRSTY del 128 



FIRSTYLACE 


del 


256 


ANGLE 


del 





PIWHOLE 


del 


$C90FDB42 


PIOVER2 


del 


SC90FDB41 


TWOPI 


del 


SC90FDB43 


PHWHOLE 


del 





PH0VER2 


del 





CURXFP 


del 


3 


CURYFP 


del 





NEWXFP 


del 





NEWYFP 


del 





TWOFP 


del 


$80000042 


XOFP 


del 





YOFP 


del 





NANGLES 


del 





COSANGLE 


del 





LOGLEN 


del 





LEVEL 


dew 





LEVELO 


dew 





ANGLENUM 


dew 






XINCARAY ds.l 16 

YINCARAY ds.l 16 

NARAY ds.l 3.6 

ANGLEARAY ds.l 16 
EVENPC 

HILBERTDRAW 
PUSHALL 

move.l WINDOW, A0 
move.l #$FFFF,D0 
INTLIB OFFMENU 
move.l WINDOW, A0 
tst.l MYLACE 
beq.s ONLYSEVEN 
cmpi.w #8, J 
beq DONEHILBERT 
bra.s ONEH 

ONLYSEVEN 
cmpi.w #7, J 
beq DONEHILBERT 

ONEH 
addi.w fl,J 
tst.l MYLACE 
beq.s ONLYSEVEH 
cmpi.w #8, J 
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beq DONEHILBERT 

bne.s SETITNOWH 
ONLYSEVEH 

cmpi.w #7, J 

beq DONEHILBERT 
SETITNOWH 

move.l WINDOW, A0 

bsr _CLEARWINDOW 

move.w J,R 

moveq #0,D0 

move.w R, D0 

move.l #128, Dl 

lsr.w D0.D1 

move.w D1,Q 

SETDRMD RP,#JAM1 
SETAPEN RP,#1 
move.w #8,X 
move.w #30, Y 
tst.l MYLACE 
beq.s NOTYHEIGHTH 
move.w #30, Y 
NOTYHEIGHTH 
DRAWPOINT RP,X,Y 
bsr HILFRAC 

move.l #TICKSPERSECOND,Dl 
;asl.w #1,D1 
DOSLIB DELAY 
bra ONEH 

HILFRAC: 

PUSHALL 

subq.w #1,R 

eori.w #1,T 

bsr HILARITH 

tst.w R 

ble.s M0 

bsr HILFRAC 
H0 

bsr DOALINE 

eori.w #1,T 

bsr HILARITH 

tst.w R 

ble.s HI 

bsr HILFRAC 
HI 

bsr DOALINE 

tst.w R 

ble.s M2 

bsr HILFRAC 
M2 

bsr HILARITH 

eori.w #1,T 

bsr DOALINE 

tst.w R 

ble.s H3 

bsr HILFRAC 
H3 

bsr HILARITH 

eori.w #1,T 

addq.w #1,R 

PULLALL 

rts 

HILARITH 

moveq #0,D0 

move.w Q,Z 

tst.w T 

bne.s PLUSP 
MINUSP 

sub.w P,D0 

move.w D0,Q 

move.w Z,P 

rts 
PLUSP 

move.w P.O. 

sub.w Z,D0 

move.w D0,P 

rts 
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DOALINE 

moveq #0 , D0 

move.w P,D0 

asl.w #2.D0 

add.w X,D0 

move.w D0,T, 

move.w Y,D0 

add.w Q,l)0 

tst.l MYLACE 

beq.s NOTDOUBLEY 

add.w Q, D0 
NOTDOUBLEY 

move.w D0,M 

DRAWLINE RP,X,Y,L,M 

move.w L,X 

move.w M,Y 

rts 

DONEHILBERT 

PULLALL 

move.w #0,J 

moveq #O,D0 
QUITH 

rts 

EVENPC 

X dew 

Y dew 

L dew 

M dew 

J dew 

Q dew 128 

R dew 1 

T dew 1 

Z de w 

P dc.w 

EVENPC 

DRAGONDRAW 
PUSHALL 

move.l WINDOW, A0 
move.l #$FFFF,D0 
INTLIB OFFMENU 
move.w #7,MAXLEVEL 
tst.l MYLACE 
beq.s NOTMAXEIGHT 
move.w #8,MAXLEVEL 

NOTMAXEIGHT 
move.w MAXLEVEL.D0 
cmp.w NB, D0 
beq DONEDRAGON 

ONEED 

move.w #1,NB 
ONED 

move.l WINDOW, A0 

bsr _CLEARWINDOW 

moveq #0,D0 

move.w NB,D0 

move.l D0,D1 

asl.w #i,Dl 

move.w Dl ,NC 

addq.w #1,D1 

move.w D1,ND 

move.l #128, D4 

lsr.w D0,D4 

move.w D4,DY 

asl.w #1,D4 

move • w D4 , DX 

tst.l MYLACE 

beq.s SHORTY 

move.w DY,D4 

asl.w #1,04 

move.w D4,DY 
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SHORTY 

SETDRMD RP,#JAM1 

SETAPEN RP,#1 

move.w #150, XX 

move.w #120, YY 

tst.l MYLACE 

beq.s HIWHY 

move.w #225, YY 
HIWHY 

DRAWPOINT RP,XX,YY 

lea SARAY.A4 
moveq #0,00 
move.w #32, D0 
ZERORAY 
clr.w 0(A4,D0.W) 
subq.w #2,D0 
tst.w D0 
bpl.s ZERORAY 

FRACLOOP 
move.l #SARAY,A4 
move.l #SARAY,A3 
adda.l #2, A3 
moveq #J.,D1 
moveq #0, D0 

MAKED 

cmpm.w (A3)+, (A4)+ 

bne.s DPLUSONE 

subq.w #2,D0 
DPLUSONE 

addq.w #1,D0 

bpl.s CHEKIFATE 

move.l #7,D0 
CHEKIFATE 

cmpi.w #8,D0 

bne.s CPLUSONE 

moveq. 1 #0,00 
CPLUSONE 

addq.w #1,D1 

cmp.w ND,D1 

bne.s MAKED 

moveq #0,D2 

moveq #0,D3 

move.w XX, D2 

move.w YY,D3 

tst.w D0 

beq.s RIGHT 

cmpi.w #2,D0 

beq.s UP 

cmpi.w #4,D0 

beq.s LEFT 
DOWN 

sub.w DY, D3 

bra. a TWO 
UP 

add.w DY.D3 

bra . s TWO 
LEFT 

sub.w DX,D2 

bra.s TWO 
RIGHT 

add.w DX,D2 

TWO 
move . w D2 , XN 
move.w D3,YN 
DRAWLINE RP,XX,YY,XN,YN 
move.w D2,XX 
move.w D3,YY 

moveq #0 , D0 
move.w NC,D0 
asl.w #1,D0 
move.l #SARAY,A4 
addi.w #1,0(A4,D0.W) 



u 

u 
u 
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ARAYLOOP 
cmpi.w #2,0(A4,D0.W) 
bne.s THREE 
clr.w 0(A4,D0.W) 
subq.w #2,00 
addi.w #1,0(A4,D0.W) 
tst.w D0 
bne.s ARAYLOOP 

THREE 
move.w SARAY,D0 
beq FRACLOOP 

move.l #TICKSPERSECOND, Dl 
DOSLIB DELAY 
addi.w #1,NB 
move.w MAXLEVEL.D0 
cmp.w NB, D0 
bne ONED 

DONEDRAGON 

PULLALL 

move.w #;. ,NB 

moveq #0 , D0 
QUITNOWD 

rts 

EVENPC 

MAXX dew 
MAXY dew 

DX dew 
DY dew 
XN dew 200 
YN dew 100 
XX dew 200 
YY dew 100 
NB dew 1 
NC dew 
ND dew 
MAXLEVEL dew 8 

EVENPC 
SARAY DS.W 32 

EVENPC 

OSAGETEXT 

deb 'Usage: POLYPRAC , 10,0 

EVENPC 
ERRORTEXT 

deb 10, 'Sorry, cannot open new window. ', 10, 

EVENPC 
MYMESSAGE 

deb 10,10,' POLYPRAC by Daniel Wolf Copyright 1988 by ',10 

deb ' Compute! publications ',10,0 

EVENPC 

STACK del 
WINDOW del 
RP del 
MYLACE del 
_THISMENU del 

DRAGTITLE deb ' POLYPRAC BY D.WOLP ',0 

EVENPC 
MYMUEXES del $1E, ?1D, SIB, 517, $P, 0,0,0 
MYMENUT1TLE ;THIS IS A MENU1I 

deb ' POLYPRAC ',0 

EVENPC 
ITEM0 

de b ' DRAGON ' , 

EVENPC 
ITEM). 

deb ' HILBERT ',0 

EVENPC 
ITEM2 

deb ' TRITREE ',0 

EVENPC 
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ITEM3 

dc.b ' QUADTREE ' ,<S 

EVENPC 
ITEM4 

dc.b ■ QUINTREE ',0 

EVENPC 
ITEM5 

dc.b • QUIT ' ,0 

EVENPC 
MYCMDKEYS 

dc.b 'DH345Q',0 

EVENPC 
_THISFONTHITE 
~"dc.w 9 

END 
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LENS.ASM 

This is a simple graphic program that combines an adapting 
window (see POLYFRAC.ASM) with a routine that magnifies 
a selected region surrounding the pointer. Wherever the 
pointer is located on the screen becomes the center of the 
magnified image. A proportional gadget slider control allows 
you to select eight different magnification factors. 

When the program begins, the magnification factor is pre- 
set to half its maximum and the window is filled with a mag- 
nified view of wherever the pointer is. After the window fills, 
you can change magnification factors or size the window. No 
change will result from these operations. To activate the mag- 
nification routine, press the right mouse button. If the usual 
left button select mechanism had been used, you might have 
had to wait for a magnification operation every time you re- 
sized your window. This way, you can use the left mouse but- 
ton to manipulate the window and slide control, and then 
move the pointer where you wish and press the right button 
to start the magnification routine. 

You can also call this program from the CLI. Try using 
LENS ? to make the program print out its own command for- 
mat. You'll see from the code that it's easy to make a program I \ 
see the question mark. Many programs have a standard ? L — ' 
mechanism for printing their own command formats. It's easy 
and it adds a professional touch to any program called from 
the CLI. 

Listing 23-3. LENS.ASM 

.-LENS. ASH by Daniel Wolf 

jCopyright 1988 by Computet publications 
;09/10/87 

bra _START 

DOS equ 1 
GFX equ 3. 
INT equ 3. 



318 



u 
u 
u 

u 



n 



Amiga Machine Language Programming 



n 



WIN equ I. 
TXT equ 1 
GAD equ 1 

include "HEADER" 

MINX equ 4 

MI NY equ 1.3. 

MAIN 

move.l SP, STACK 

REMEMBERCHIPMEM REMEMBERKEY, «j 6 iTHIS ARRAY MUST BE IN CHIP MEM1 

lea TEMPLATE, A0 

move.l DO, (A0) 

bne.s ARRAYOK 

moveq #22,019 

bra QUIT 
ARRAYOK 

move.l #-l,D0 

movea.l TEMPLATE, A0 

move.l D0, (A0) + 

move.l D0, (A0)+ 

move.l D0, (A0)+ 

move.l DO, (A0) 

CHKFROMCLI 

tst.l ENDPROMCLI 

beq LENSPROMWB 

DOSPRINT STDOUT, SMYMESSAGE 

move.l COMMAND, A0 

cmp.b #'?',(A0) ;SEE IF THIS CHAR IS A ASCII ? 

bne.s CHKGRID 

beq USAGE ; SHOW USAGE 

CHKGRID 

cmp.b *'G',(A0) jSEE IF COMMAND LINE CHAR IS ASCII G 

bne.s CHKMAG 

move.w #1,GRID ;SET GRID FLAG 

adda.l #2,A0 
CHKMAG 

clr.l D0 

move.b (A0).D0 ;SEE IF THIS OR NEXT CHAR IS ASCII 1-8 

cmp.b #'8',D0 

bhl.s LENSPROMWB 

cmp.b #•>.' ,D0 

blt.s LENSPROMWB 

andi.b #$0F,D0 

move.w DO, MAG (YES, SAVE IT AS MAG FACTOR 

LENSPROMWB 
lea _THISIDCMP,A0 

move.l #MENUPICKICLOSEWIND0W, (A0) 
MAKEWIN ftLENSTITLE, 240, 65, 1 60,63, MYERROR 
move.l DO, WINDOW 
move.l D0,A0 
move.l WW.RPORT(A0),A! 
move.l WW.WSCREEN(A0),A2 
lea SCRN.RASTPORT(A2),A3 
move.l A1,RP 
move.l A2, SCREEN 
move.l A3.SCRP 
SETDRMD AX , # JAM* 
INTLIB VIEWPORTADDRESS 
move .1 D0 , AO 
move.w VP. MODES (A1),D1 
and.w #LACE,D1 
beq.s NOTLACEHEIOHT 
move.l #1,MYLACE 
move.l WINDOW, A0 
move.w WW.HEIGHT(A0),D1 
ZERO DO 

INTLIB SIZEWINDOW 
move.l #TICKSPERSECOND/4,D3. 
DOSLIB DELAY 
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NOTLACEHEIGHT 
clr.l D3 
move.w #0,D4 
move.w #-8,D5 
move.w #-;.2,D6 
move.w #8,D7 

bsr MAKEAPROPGADGET ; HORIZONTAL GADGET 

move.l WINDOW, A0 
move.l _THISGADGET,A1 
move.l A1,_BAR 
move . w GADG ■ FLAGS ( AJ ) , D0 
ori.w #GRELBOTTOMIGRELWIDTH,D0 

move.w D0, GADG. FLAGS ( A; ) ;SET FLAGS FOR HORIZONTAL BOTTOM BAR 

move.l GADG.SPECIALINFO(Al ),A2 

move.w #$2000,PI.HORIZBODY(A2) ;SET BODY TO ; EIGHTH 
move.w #$IFFF,DJ. 
move.w MAG,D0 
mulu 01, D0 

move.w D0,PI.HORIZPOT(A2) 
ZERO D0 
move.w #-*,D0 

INTLIB ADDGADGET ;ADD THE GADGET 

move.l _BAR,A0 ;SAVE POINTER TO BAR GADGET 

move.l WINDOW, A; 
INTLIB REFRESHGADGETS ;MAKE IT APPEAR 

GETNEWPARAMS 
bsr LENSWPARAMS 
bra BLITLOOP 

LOOP 
move.l WINDOW, A0 
move.l WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
move.l WINDOW, AO 
move.l WW.USERPORT(A0),A0 
SYSLIB GETMSG 
tst.l D0 

beq.s BLITLOOP ;NO MESSAGE, SO DO THE COPV LOOP 

move.l D0,a; 
move.l IM. CLASS (A; ) , Dl 
SYSLIB REPLYMSG 
cmp.l *CLOSEWINDOW,D2 
beq DONE 
bra GETNEWPARAMS ;IF MESSAGE NOT CLOSEWINDOW, THEN DO BLIT 

BLITLOOP 

PUSHALL 

movea.l SCREEN, Al 

move . w SCRN . MOUSEX ( A; ) , MOUSEX 

move.w SCRN. MOUSEY(Al), MOUSEY 

move.l TEMPLATE, A3 

move.l RP,A4 

move.l SCRP.A5 

move.w MAG,D4 

move.w D4,D5 

ZERO D7 :SCREENY = 

move.w MOUSEY, D7 

sub.w SCSTARTY, D7 ;SCREENY = SCREENY + MOUSEY 

move.w #MINY,D3 ;WPOSY = MINY 

LOOPY 

ZERO D6 .-SCREENX = 

move.w MOUSEX, D6 

sub.w SCSTARTX.D6 ;SCREENX = SCREENX + MOUSEX 

move.w #MINX-1,D2 ;WXPOS = MINX 
LOOPX 

cmp.w SWID.06 ;IF SCREEN WIDTH < SCREENX FORGET IT 

bge.s BLITNOW ; USE ZERO COLOR 

cmp.w SHIT.D7 ;IP SCREEN HEIGHT < SCREENY FORGET IT 

bge.s BLITNOW ; USE ZERO COLOR 

READPOINT A5,D6,D7 ;GET SCREEN PIXEL COLOR AT POSITION D6,D7 

BLITNOW 

SETAPEN A4 ;SET WINDOW DRAWING PEN WITH THIS COLOR 

ZERO D0 ;D0 = 

moveq #2,D1 ;D1 = 2 

move.l A3.A0 ;TEMPLATE POINTER IN A0 

move.l A4,A1 ;LENS WINDOWS RASTER PORT POINTER IN A). 



u 

u 

u 
u 
u 
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JUST BLTTEMPLATE 
addq.w #- , D6 
add.w SKIPX, D2 
cmp.w WLIMX, D2 
bls.s I.OOPX 
addq.w #3. ,D7 
add.w SKIPY, D3 
cmp.w WLIMY, D3 
bis LOOPY 
PULLALL 
bra LOOP 

DONE 

clr.l D0 
QUIT 

move.l STACK, SP 

move.l D0,-(SP) 

move.l WINDOW, D0 

beq.s 1$ 

move.l D0,A0 

INTLIB CLOSEWINDOW 
1$ 

move.l (SP)+,D0 

rts 



LENSWPARAMS 
PUSHALL 

move.l WINDOW, A0 
move.w WW.WIDTH(A0),D0 
subq.w #3,D0 
move.w D0,MAXX 
move.w WW.HEIGHT(A0),D1 
subq.w #2,D3. 
subq.w #S,D3. 
move.w D3. ,MAXY 



;BLIT IT 1 1 
; SCREENX = SCREENX + 1 
;WXPOS = WXPOS + SKIPX 
;IP WPOSX < WLIMX THEN 
; ANOTHER X PIXEL 
SCREENY = SCREENY + 1 
WYPOS = WYPOS + SKIPY 
IF WPOSY < WLIMY THEN 
ANOTHER Y LINE 



[MAXX = LENS WINDOW WIDTH 



.•COMPENSATE FOR SCROLL BAR 
;MAXY = LENS WINDOW HEIGHT 



movea.l _BAR,A0 

movea.l GADG.SPECIALINFO(A0) ,A3 

clr.l D0 

olr.l Dl 

move.w pi.horizpot(a;.),d0 

lsr.l #8,D0 

lsr.l «5,D0 

addi.w #1 , D0 

move.w D0,MAG 



add.w GRID.D0 
move.w D0, SKIPY 
add.w GRID.D0 
move.w D0, SKIPX 
clr.l D7 
move.w MAXY.D7 
sub.w #MINY-3.,D7 
divu SKIPY, D7 
lsr.w #I,D7 
move . w D7 , SCSTARTY 
clr.l D6 
move.w MAXX.D6 
sub.w #MINX-3.,D6 
divu SKIPX, D6 
lsr.w #).,D6 
move . w D6 , SCSTARTX 
movea.l SCREEN, A,, 
move.w SCRN.WIDTH(A).) 
move.w SCRN. HEIGHT (A3, 
moveq .1 #0 , D0 
move.w MAXX.D0 
sub.w MAG , D0 
addq.w #3.,D0 
move.w D0, WLIMX 
moveq. 1 #0,D1 
move.w MAXY, Dl 
sub.w MAG.D1 
addq.w #1,D1 
move.w Dl, WLIMY 
PULLALL 
rts 



1 SKIPY = MAG + GRID 

j SKIPX = MAG + 2*GRID 

; SCREENY = 

; SCREENY - MAXY 

! SCREENY = MAXY - (MINY-1) 

jSCREENY = (MAXY - (MINY-1) 1/SKIPY 

. SCREENY = SCREENY/ 2 

; SCREENX = 

; SCREENX = MAXX 

;SCREENX = MAXX - (MINX-1) 

;SCREENX = (MAXX - (M1NX-J.) 1/SK1PX 

; SCREENX = SCREENX/ 2 

;LENS' SCREEN STRUCTURE POINTER IN Al 
, SWID 
),SHIT 

;D0 - MAXX 

;D0 » MAXX - MAGFACTOR 

;D0 = MAXX - MAGFACTOR +3. 



Dl = MAXY 




Dl = MAXY 


- MAGFACTOR 


D3. = MAXY 


- MAGFACTOR 
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MYERROR 
DOSPRINT STDERR, fERRORTEXT 
moveg #21,00 
bra QUIT 

USAGE 
DOSPRINT STDERR, #USAGETEXT 
clr.l D0 
bra QUIT 

MYMESSAGE 

dc.b 10, 'LENS by Daniel Wolf Copyright 1988 by Compute! Publications* , 10,0 

EVENPC 
ERRORTEXT 

dc . b ' Cannot open window ' , 

EVENPC 
USAGETEXT 

dc.b "Usaget LENS [G Grid] [# Mag( 1-8)] ' , 10, 

EVENPC 
LENSTITLE 

dc.b • LENS by D.Holf ',0 

EVENPC 

STACK del 

WINDOW do.l 

SCREEN del 

RP del 

SCRP del 

TEMPLATE del 

_BAR del 

MYLACE del 

MAXX dew 

MAXY dew 

MOUSEX dew 

MOUSEY dew 

SHIT dew 

SWID dew 

SKIPX dew 

SKIPY dew 

WLIMX dew »J 

WLIMY dew 

SCSTARTX dew 

SCSTARTY dew 

MAG dew 4 

GRID dew 
JTHISFONTHITE dew 9 

EVENPC 

END 

QUADRIX.ASM 

QUADRIX.ASM is a 3-D graphics generation program that 
draws quadric surfaces (paraboloid, hyperbolic paraboloic, hy- 
perboloid, ellipsoid, and cone). The program combines a win- 
dow, menu, and three proportional (slider) gadgets with 
floating-point and transcendental (trigonometric) math 
routines. This program uses all the libraries discussed in this 
book, including AmigaDOS, Intuition, Graphics, MathFFP, and 
MathTrans. 

The slider gadgets partly control the angle of view for the 
three-dimensional solid shape. Since the angle of view partly 
determines how large the shape is drawn, there will be occa- 
sions when the surfaces may seem too large or too small for 
the window. You can adjust the SCALE factors. These factors 



U 
U 



u 



u 
u 
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are well-commented in the source code. Scale factors were se- 
lected to make the ellipsoid fill the window. 

When the window is resized, the image is not redrawn. 
You'll have to select from the menu again to get a new image. 
Redrawing the image takes several seconds, in some cases, 
and might make an aggravating delay when all you want to 
do is resize. It's the same tradeoff as in LENS.ASM, which 
also does not redraw the image until commanded by the user. 

The reason for the program's length is the math involved 
in calculating equations for all five quadric surface shapes. The 
extensive calculations are commented so that you can see how 
they could be translated into other languages. 

Listing 23-4. QUADRIX.ASM 

;QUADRIX.ASM by Daniel Wolf 

;C0PYRIGI1T ;.9*)8 BY COMPUTEI PUBLICATIONS 
;09/;.!l/a7 

bra _START 

;FOR LIBRARIES IN STARTUP. ASM (INCLUDED BY HEADER) 
GFX equ ". 
MAT equ ; 
TRA equ • 

;POR INCLUDES HEADER 
WIN equ ; 
TXT equ * 
GAD equ 1 
MEN equ : 

;MATHTYPES FOR MATH. ASM 
FFP equ *.. 
HEX equ ; 

include "HEADER" 

MAIN 

move.l SP, STACK 

move . 1 ENDFROMWB , D0 

beq.s FROMUSER 

bra.s NOWTHEWINDOW 
FROMUSER 

DOSPRINT STDOUT, SMYMESSAGE 
NOWTHEWINDOW 

move.l #4, SHAPE 

move.l *0,HMIN 

move.l #0,LMIN 

MAKEWIN #DRAGTITLE, 5. 30,430, 158, ERROR 

move.l #430,HMAX 
move.l #158,LMAX 
move.l D0, WINDOW 

move.l D0,A0 

move.l WW.RPORT(A0),RP ;SAVE POINTER TO RASTPORT OF WINDOW 

1NTLIB VIEWPORTADDRESS ;GET POINTER TO VIEWPORT OF WINDOW 

move.l D0,A0 

move.w VP. MODES (A0),D). 

and.w #LACE,D1 ;ARE WE IN INTERLACE MODE? 

beq.s NOWMAKEQMENU 

move.l #;.,MYLACE 

move.l WINDOW, A0 

moveq.l #0,D0 

moveq.l #0,d: 
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move.w WW.HEIGHT(A0),DJ ;IP so, double window height 

INTLIB SIZEWINDOW 



u 
u 



NOWMAKEQMENU 
MITEMLIST ITEM0, ITEM; ., ITEM2, ITEM3, ITEM4, ITEMS, 0,0, 5 
MAKEMEN MYCMDKEYS , MYMUEXES , MYMENUTITLE , ERROR 
move.l D1,_THISMENU 
move.l #5,D0 
move.l #7 5, Di 
bsr CREATEMENU 

move.l WINDOW, AG 
move.l _THISMENU,A3. 
INTLIB SETMENUSTRIP 

YANGLEBAR 
move . b # ' V ' , D3 
move.w #-3.5, D4 
move.w #3.0, D5 
move.w #3.5, D6 
move.w #-3.8, D7 
bsr MAKEAPROPGADGET 
move.l WINDOW, A0 
move.l _THISGADGET,A3 
move .1 A3 , _YBAR 
move.w GADG. FLAGS ( A3 ),D0 
ori.w #GRELRIGHTlGRELHEIGHT,D0 
move.w DO, GADG. FLAGS (A3) 
clr.l D0 
move.w #-3.,D0 
INTLIB ADDGADGET 
ZANGLEBAR 
move.b #'V ,D3 
move.w #0,D4 
move.w #3.0, D5 
move.w #3. 5,D6 
move.w #-18, D7 
bsr MAKEAPROPGADGET 
move.l WINDOW, A0 
move.l _THISGADGET,A3 
move.l A3,_ZBAR 
move . w GADG . FLAGS ( A3 ) , D0 
ori.w #GRELHEIGHT, D0 
move .w D0, GADG . FLAGS (A3 ) 
clr.l D0 
move.w #-3.,D0 
INTLIB ADDGADGET 
XANGLEBAR 
clr.l D3 
move.w #0,D4 
move.w #-8,D5 
move.w #-3. 5,06 
move.w #8,D7 
bsr MAKEAPROPGADGET 
move.l WINDOW, A0 
move.l _THISGADGET,A3 
move.l A3. ,_XBAR 
move.w GADG . FLAGS ( A3 ), D0 
ori.w #GRELBOTTOMI'3RELWIDTH,D0 
move . w DO , GADG . FLAGS ( A3 ) 
clr.l D0 
move.w #-3 , DO 
INTLIB ADDGADGET 

move.l _YBAR,A0 
move.l WINDOW, A3 
INTLIB REFRESHGADGETS 

ANNOUNCEMENT 
movea.l WINDOW, A5 
moveq #0 , 00 
moveq #0,D3 

PRINTNEWAT A5.TEXT3, 30, 20, ERROR 
PRINTNEWAT A5.TEXT2, 40, 30, ERROR 
PRINTNEWAT A5, TEXT3, 50, 40, ERROR 



u 
u 
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move.l #TICKSPERSECOND/2,DJ. 
DOSLIB DELAY 

NEWWPARAMS 
clr.l D0 

move.l WINDOW, A0 
move.w WW. HEIGHT) A0),D0 
move.l D0.LMAX 
eub.w #15, D0 
move.w D0.LMAXW 
move.w WW.WIDTH(A0),D0 
move.l D0,HMAX 
sub.w #15, D0 
move.w D0.HMAXW 

LOOP 
move.l WINDOW, A0 
move.l »SPFPF,D0 
INTLIB ONMENU 
move.l WINDOW, A0 
move.l WW.USERPORT(A0),A0 
SYSLIB WAITPORT 
move.l WINDOW, A0 
move.l WW.USERPORT(A0),A0 
SYSLIB GETMSG 
tst.l D0 
beq . s LOOP 
move.l DO, A j. 
move.l IM. CLASS (A; ) , D2 
move.w IM.CODE(Aj ),D3 
move.w IM.QUALIFIER(A1),D4 
SYSLIB REPLYMSG 
empi.l #CLOSEWIND0W, D2 
beq DONE 
tst.l PIRSTTIME 
beq QMYTIME 
ompi.l #NEWSIZE,D2 
beq NEWWPARAMS 



CHKQMEHU 

ompi.l #MENUPICK,D2 

bne QMYTIME 

moveq.l #O,D0 

move.w D3,D0 

bar MENUEVENT 

cmpi.w #5,D1 

beq DONE 
CHKPARAB 

cmpi.w #0,D1 

bne.s CHKHYPPAR 

move.l #1, SHAPE 

bsr QSURFACE 

bra QMYTIME 
CHKHYPPAR 

cmpi.w #1,01 

bne.s CHKHYPHYP 

move.l #2, SHAPE 

bsr QSURFACE 

bra QMYTIME 
CHKHYPHYP 

cmpi.w #2,D1 

bne.s CHKELLIP 

move.l #3, SHAPE 

bsr QSURFACE 

bra QMYTIME 
CHKELLIP 

cmpi.w #3,D1 

bne.s CHKCONE 

move.l #4, SHAPE 

bsr QSURFACE 

bra.s QMYTIME 
CHKCONE 

cmpi.w #4,D1 

bne.s QMYTIME 

move.l #5, SHAPE 

bsr QSURFACE 



[PARABOLOID 1 



; HYPERBOLIC PARABOLOID 2 



,-HYPERBOLOID ONE SHEET 3 



; ELLIPSOID 4 



;CONE 5 
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QMYTIME 
move.l #1,FIRSTTIME 
bra LOOP 

QSURFACE 

move.l #0,NEGNECESSARY 

move.l #0, DENSE 

move.l WINDOW, A0 

move.l #$FPPF,D0 

INTL1B OFFMENU 

PUSHALL 

movea.l _MATHTRANSBASE, AS 

movea.l _MATHBASE,A4 

move.l A4,A6 

move.l hmax,d0 

sub.l HMIN.D0 

move.l D0.HRES 

move.l LMAX.D0 

sub.l LMIN.D0 

move.l D0,LRES 

move.l HRES.D0 

lsr.l #1,00 

add.l HMIN.D0 

move.w D0,HC 

move.l LRES,D0 

lsr.l #;.,D0 

add.l LMIN.D0 

move.w D0.LC 

move.l D0,d; 

lsr.l #:,D1 

move.l SHAPE, D7 

cmp.l #1,07 

bne.s YINCOK 

add.l D1,D0 
YINCOK 

move.w D0,LC 

move.l #40, D0 

JUST SPPlt 

move.l D0,D7 

move.l HMAX.D0 

JUST SPFlt 

move.l D7,D". 

JUST SPDiv 

move.l D0.SCALEH 

move.l #;.25,D0 

JUST SPFlt 

move.l D0,D7 

move.l lmax.00 

JUST SPFlt 

move .1 D7 , Dl 

JUST SPDiv 

move.l D0.SCALEV 
BARSETTINGS 

movea.l _YBAR,A0 

move.l GADG.SPECIALINFO(A0),A0 

move.w PI.VERTPOT(A0),GYANGLE 

movea.l _XBAR,A0 

move.l GADG.SPECIAL1NFO(A0),A0 

move.w PI.HORI7,POT(A0),GXANGLE 

movea.l _ZBAR,A0 

move.l GADG.SPECIALINFO(A0),AO 

move.w PI.VERTPOT(A0),GZANGLR 



u 
u 
u 
u 



; POINTER TO MATHTRANS LIBRARY IN A5 
f POINTER TO MATH LIBRARY IN A4 
;USE THE MATH LIBRARY NOW 



;HRES = HMAX - HMIN 
;LRES = LMAX - LMIN 



;HC = 2*HRES + HMIN 



;LC = 2*LRES 4 

;D0 = LC 

;D1 = 2*LC 

;D7 = SHAPE 

;IF SHAPE <>1 
;D0 = D0 + D3. 



;LC = 3*LC 



;SCALEH = HMAX/40 



;SCALEV = LMAX/12S 



SHAPECHANGE3 
move.l SHAPE, D7 
cmp.l #4,D7 
bne.s TWONSHAPE 
move.l #7,D0 
JUST SPFlt 
move.l SCALEH.D). 
JUST SPMul 
move.l D0.SCALEH 
move.l #25, D0 
JUST SPFlt 
move.l SCALEV.D). 
JUST SPMul 
move.l D0,SCALEV 



; RESET SCALES FOR ELLIPSOID 



;SCALEH = 3*SCALEH 



;SCALEV = 3.3*SCALEV 
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move.l Itl.NEGNECESSARY 

move.l #1, DENSE 
TWONSHAPE 

cmp.l #3»D7 

bne.s THIRDBSHAPE 

move.l TWOFP.D0 

move.l SCALEV.D). 

JUST SPMul 

move.l D0.SCALEV ;SCALEV = 2*SCALEV 

move.l #1,NEGNECESSARY 
THIRDNSHAPE 

omp.l #5,D7 

bne.s CORNERANGLES 

move.l TWOFPiDU 

move.l SCALEV.DJ 

JUST SPMul 

move.l D0.SCALEV jSCALEV = 2*SCALEV 

move.l #1,NEGNECESSARY 

CORNERANGLES 
clr.l D0 
move . w LC , D0 
sub.l LMIN.D0 
JUST SPPlt 
move.l D0.LCMINLMIN 
move.l LMAX.D0 
sub.w LC,D0 
JUST SPFlt 
move.l D0.LMAXMINLC 
move.l HMAX.D0 
sub.w HC,D0 
JUST SPFlt 
move.l D0.HMAXMINHC 
move.w HCD0 
sub.l HMIN.D0 
JUST SPPlt 
move.l D0.HCMINHMIN 

move.l LCMINLMIN.D0 

move.l HMAXM1NHC, D). 

JUST SPDiv 

move.l A5,A6 

JUST SPAtan 

move.l D0,C1 

move.l A4.A6 

move.l LCMINLMIN.D0 

move.l HCMINHMIN, Dl 

JUST SPDiv 

move.l A5/A6 

JUST SPAtan 

move.l D0,C2 

move . 1 A4 1 A6 

move.l LMAXMINLCD0 

move.l HCMINHMIN, Dl 

JUST SPDiv 

move.l A5,A6 

JUST SPAtan 

move.l D0.C3 

move . 1 A4 , A6 

move.l LMAXMINLC.D0 

move.l HMAXMINHCD1 

JUST SPDiv 

move "• 1 A5 , A6 

JUST SPAtan 

move . 1 D0 , C4 

move.l A4.A6 ;REGMATH 

move.l PIWHOLB.D0 

move.l D0.D7 

move .1 C2 1 D5. 

JUST SPSub 

move.l D0,C2 

move.l D7,D0 

move.l C3.D3. 

JUST SPAdd 

move.l D0,C3 

move .1 D7 , D0 

add.l #;.,D0 
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move.l C4,D1 
JUST SPSub 
move.l D0,C4 

SETXVZANGLES 

move.l #16384,00 
JUST SPFlt 
move.l D0,D7 
move.l PIWH0LE.D6 

clr.l D(5 

move.w GXA>JGLE,D0 
JUST SPFlt 
move .1 D7 , Dl 
JUST SPDiv 
move.l D6,D1 
JUST SPMul 
move.l D0,XANGLE 
clr.l D0 

move.w GYANGLE.D0 
JUST SPFlt 
move.l D7,D1 
JUST SPDiv 
move.l D6 f Dl 
JUST SPMul 
move.l D0,YANGLE 
clr.l D0 

move.w GZANGLE, D0 
JUST SPFlt 
move.l D7,D1 
JUST SPDiv 
move.l D6,D1 
JUST SPMul 
move.l D0.ZANGLE 

move.l XANGLE.D0 
move.l #COSXA, Dl 
move.l A5,A6 
JUST SPSincos 
move.l D0,SINXA 

move.l YANGLE.D0 
move.l #C0SYA,D1 
JUST SPSincos 
move.l D0.SINYA 

move.l ZANGLE.D0 
move.l #C0SZA,D1 
JUST SPSincos 
move.l D0.SINZA 

move.l A4,A6 
move.l #26, D0 
JUST SPFlt 
move.l HUNDFP.Dl 
JUST SPDiv 
move.l D0,STEPI 
subi.l #1,D0 
move.l D0.STEP2 
subi.l #1,00 
move.l D0,STEP3 

DRAWSURFACE 
SETAPEN RP,#1 
move.w #14, D0 
move.w #10, Dl 
move.l WINDOW, A0 
move.w WW.WIDTH(A0),D2 
subi.w #14, D2 
move.w WW.HEIGHT(A0),D3 
subi.w #10, D3 
RECTFILL RP 

move.l A4.A6 
tst.l MYLACE 
bne.s LACESCALE 
subi.l # I, SCALE V 



fANGLE = PROPGADGET/16384 * PI 



;TRANSMATH 



u 
u 
u 
u 

U 
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LACESCALE 

move.l #6,D0 ;FOR TY = -6 TO +6 STEP .4 

JUST SPFlt 

move.l D0.LASTTY 

move.l D0.PLUSIX 

JUST SPNeg 

move.l D0.MINSIX 

move.l MINSIX.A3 
NEXTYY1 

move.l #0,D0 

move.l D0.A2 

move.l STEP! /D0 

tst.l DENSE 

beq.s NOTDENSE 

move.l STEP2.D0 
NOTDENSE 

move.l D0.STEPTY 

move.l D0, STEPTX 

move.l PLUSIX.LASTTX ;FOR TX = TO 6 STEP STEPTTX 

SETAPEN RP,#2 
NEXTXX1 

move.l A2.D0 

move . 1 A3 , Dl 

bsr PROSCALE 

DRAWPOINT RP.MH.MV 

move.l A4,A6 

tst.w MH 

beq.s CONTXX1 

tst.l NEGNECESSARY 

beq.s CONTXX1 

move .1 Al , D0 

JUST SPNeg 

bsr FUNCDONE 

DRAWPOINT RP.MH.MV 

move.l A4.A6 
CONTXX3. 

move.l A2.D0 

move.l STEPTX, Di 

JUST SPAdd 

move.l D0.A2 

move.l D0.D1 

move.l LASTTX.D0 

JUST SPCmp 

bgt NEXTXX1 

move.l MINSIX.A2 

move.l #0,D0 

move.l D0.LASTTX 

move.l STEP2.D0 

tst.l DENSE 

beq.s NOTDENS2 

move.l STEP3.D0 
NOTDENS2 

move.l D0.STEPTX ;FOR TX = -6 TO STEP STEPTX 

SETAPEN RP,#3 
NEXTXX2 

move.l A2.D0 

move.l A3.D1 

bsr PROSCALE 

DRAWPOINT RP.MH.MV 

move.l A4.A6 

tst.w MH 

beq.s CONTXX2 

tst.l NEGNECESSARY 

beq.s CONTXX2 

move .1 A3. . D0 

JUST SPNeg 

bsr FUNCDONE 
DRAWPOINT RP.MH.MV 

move . 1 A4 , A6 
CONTXX2 

move.l A2.D0 

move.l STEPTX, Dl 
JUST SPAdd 
move.l D0.A2 
move.l D0.D1 
move.l LASTTX.D0 
JUST SPCmp 
bgt NEXTXX2 
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move .1 A3 r 00 

movG.i stepty.d; 

JUST SPAdd 
move.l d0,d; 
move.l DO, A3 
move.l LASTTY.D0 
JUST SPCmp 
bgt nextyy; 

PULLALL 
rts 

PROSCALE 
FUNCDEF 

move.l A4,A6 

move.l Dl,D7 

move.l D0,D". 

JUST SPMul 

move .1 D0 , 06 

move .1 D7 , DO 

move.l D0,Di 

JUST SPHul 

move.l D6,D1 

move.l SHAPE, D5 

cmp.l #;. ,D5 

beq PARABOLOID 

cmp.l #2,D5 

beq HYPPARABOLOID 

cmp.l #3,D5 

beq HYPERBOLOIO 

cmp.l #4,D5 

beq ELLIPSOID 

cmp.l #5,D5 

beq CONE 

PARABOLOID 
JUST SPAdd 
bra FUNCDONE 

HYPPARABOLOID 
JUST SPSub 
bra FUNCDONE 

HYPERBOLOID 
JUST SPAdd 
move.l TW0FP.D3. 
JUST SPSub 
move.l A5,A6 
JUST SPSqrt 
move.l A4,A6 
addq.l #i,D0 
bra FUNCDONE 

ELLIPSOID 
move .1 Dl , D6 
move.l D0,D7 
JUST SPAdd 
move.l TENFP.D1 
JUST SPCmp 
blt.s MORELLIPSE 
move.w #!5,MH 
rts 

MORELLIPSE 
move.l TENFP.D0 
move.l D6,D1 
JUST SPSub 
move .1 D7 , D3. 
JUST SPSub 
move.l A5,A6 
JUST SPSqrt 
move.l A4,A6 
bra FUNCDONE 



jFUNCVAL = D0*D0+D;*D). FLOATING POINT 



;D6 = TX SQUARED 



;D0 = TY SQUARED ' 
;D3. = TX SQUARED 



u 

u 

u 
u 
u 
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Amu 


n 

| CONK 






1 1 JUST 


SPAdd 




move 


.1 A5,A6 




JUST 


SPSqrt 




^^_ move 


.1 A4,A6 




[ | addq 


.1 #1,D0 




' ' FUNCDONE 




move 


.1 D0,A1 




move 


.1 A2.D0 




^■■1 move 


.1 COSXA, 


Dl 


| i JUST 


SPMul 




! move 


.1 D0,D7 




move 


.1 A3,D0 




move 


.1 COSYA, 


Di 


JUST 


SPMul 




move 


1 D0,D6 




move 


.1 A1.D0 




move 


1 COSZA, 


Dl 


JUST 


SPMul 




move 


1 D6.D1 




JUST 


SPAdd 




move 


1 D7.D1 




JUST 


SPAdd 




move 


1 SCALEH,D1 


JUST 


SPMul 




JUST 


SPPix 




add.w HC,D0 




move 


w D0,MH 




move 


1 A2.D0 




move 


1 SINXA, 


Dl 


JUST 


SPMul 




move 


1 D0,D7 




move 


1 A3.D0 




move 


1 SINYA, 


Dl 


JUST 


SPMul 




move 


1 D0.D6 




move 


1 A1,D0 




move 


1 SINZA, 


Dl 


JUST 


SPMul 




move 


1 D6.D1 




JUST 


SPAdd 




move 


1 D7,D1 




JUST 


SPAdd 




move. 


1 SCALEV 


,D1 


JUST 


SPMul 




JUST 


SPFix 




move. 


w LCD1 




SUD.W D0,D1 




move. 


w Dl ,MV 




rts 






DONE 






__. move . 


1 WINDOW 


,A0 


1 INTLIB CLEARMENUSTRIP 


| DONEALL 




moveq 


#0,00 




QUIT 






move. 


1 STACK, 


SP 


™^ move . 


1 D0,-(SP) 


j move . 


1 WINDOW 


, D0 


! beq.s 


;? 




move. 


1 D0,A0 




IMTLIB CLOSEWIHDOW 


— 1 1S 






move . 


1 (SP)+, 


m 


| rts 






1 QUtTNOW 




move. 


1 STACK, 


SP 
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rts 

ERROR 
DOSPRINT STDOUT, #ERRORTEXT 
movecj #2L, D0 
bra QUITNOW 
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USAGETEXT 

dc.b 'Usage: QUADRIX' , "..0, 

EVEMPd 
ERRORTEXT 

dc.b ;.fl, 'Sorry, can not open new window. ' , 10,0 

EVENPC 
MYMESSAGE 

dc.b ;0,'QUADRIX by Danial Wolf Copyright 1988 by Compute! Publications 

EVENPC 

text; 

dc.b ' Quadric Surface Generator ',0 

EVEHPC 
TEXT2 

dc.b ' Contol Angles with Sliders, then ',0 

EVENPC 
TEXT 3 

dc.b ' Select Shape from Menu and Enjoy 1 - DW ',0 

EVENPC 
DRAGTITLE 

dc.b • QUADRIX by D.Wolf ',0 

EVENPC 



STACK 


del 





WINDOW 


del 





RP 


del 





MH 


dew 





MV 


dew 





HC 


dew 





LC 


dew 


13 


HMAXW 


dew 


a 


LHAXW 


dew 





ONEFP 


del 


58000004: 


TWOPP 


del 


$80000042 


FIVEFP 


del 


SA0000043 


TENFP 


del 


5A0000042 


HUNDFP 


del 


5C8000047 


PIWHOLE 


del 


5C90FDB42 


PI0VER2 


del 


$C90FDB4: 


NEGPI0VER2 


del 


SC90FDBC1 


MYIACE 


del 





LASTTX 


del 





LASTTY 


del 





STEPTX 


del 





STEPTY 


del 





HMIN 


del 





LMIN 


del 





HMAX 


del 





LMAX 


del 





CJ. 


del 





C2 


del 





C3 


del 





C4 


del 





XANGLE 


del 





SINXA 


del 





COSXA 


del 





Y ANGLE 


del 





SINYA 


del 





COSYA 


del 





ZANGLE 


del 





SINZA 


del 





COSZA 


del 





HRES 


del 





LRES 


del 





LCMINLMIN 


del 





LMAXMINLC 


del 





HMAXHINHC 


del 





HCMINHMIN 


del 





DDR 


del 





SCALEH 


del 


3 


SCALEV 


del 





HINSIX 


del 





PLUSIX 


del 


a 


GZANGLE 


dew 





GYANGLE 


dew 





OXANGLE 


dew 





STEP1 


del 






u 
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STEP2 del 

STEP3 del 

SHAPE del 4 

NEGNECESSARY del 
DENSE del 

EVENPC 

JTHISMENU 

del 
MYMENUTITLE ;THIS IS A MENU 1 I 

deb 'QUADRIX',0 

EVENPC 
ITEM0 

deb ' PARABOLOID ',0 

EVENPC 
ITEM1 

deb ' HPARABOLOID ',0 

EVENPC 
ITEM2 

deb ' HYPERBOLOID ',0 

EVENPC 
ITEM3 

deb ' ELLIPSOID ',0 

EVENPC 
ITEM4 

de b ' CONE ' , 

EVENPC 
ITEMS 

deb ' QUIT ',0 

EVENPC 
MYCMDKEYS 

deb •PHYECQ' 

EVENPC 
MYMUEXES 

del S1E,$1.D,5).B, $17, $F, 0,0,0 
FIRSTTIME 

del 
_THISFONTHITE 

dew 9 
_XBAR del jPOINTER TO FIRST GADGET 

_YBAR del ; POINTER TO SECOND GADGET 

_ZBAR del 3 [POINTER TO THIRD GADGET 

END 
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I APPENDIX A 

H Motorola 

n MC68000/MC68010 

U Instruction Set and ASM 
Directive Definitions 



Key 


to abbreviations used in this appendix. 


* 


Used to indicate that a condition code flag is af- 




fected by an operation 





Indicates that condition code is always cleared (set 




toO) 


1 


Indicates that condition code is always set (set to 1) 


{} 


Indicates an optional part of the statement 


— 


Used to indicate that a condition code flag is not af- 




fected by an operation 


? 


Used to indicate that a condition code flag has an 




undefined result 


ADST 


Address register as destination 


ASRC 


Address register as source 


[B/L] 


Either a byte or long word may be used by append- 




ing .B or .L to the opcode 


[B/W/L] 


Either a byte, word, or long word may be used by 




appending .B, .W, or .L to the opcode 


C 


Carry flag 


CCR 


Condition code register 


<DATA> 


Value 


DDST 


Data register as destination 


DFC 


Destination function register 


DSRC 


Data register as source 


<EA> 


Effective address 


<LABEL> Label 


N 


Negative flag 


PC 


Program counter 


RDST 


Either a data or an address register as a destination 


[R/L] 


Right or left 


RSRC 


Either a data or an address register as source 


SFC 


Source function register 
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[S/L] 


Either a short or a long word may be used by 




appending .S or .L to the opcode 


SR 


Status register 


USP 


User stack pointer 


V 


Overflow flag 


VBR 


Vector base register 


[W/L] 


Either a word or a long word may be used by 




appending .W or .L to the opcode 


X 


Extend flag 


z 


Zero flag 



Opcodes 

ABCD Instruction 

Action: Add decimal with extend 
Condition Codes: X: * N: ? Z: * V: ? C: * 
Opcode Forms: ABCD 
Assembler Syntax: 

ABCD ' DSRQDDST 

ABCD -(ASRC),-(ADST) 

Description: Add the source operand to the destination op- 
erand using Binary Coded Decimal (BCD) arithmetic. Store 
the result in the destination operand. 

ADD Instruction 

Action: Add binary 

Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: ADD, ADD.B, ADD.W, ADD.L 
Assembler Syntax: 

ADD{.[B/W/L] } <EA>,DDST . I I 

ADD{.[B/W/L] } DSRC / <EA> UJ 

ADD{.[W/L] } <EA>,ADST 

ADD{.[B/W/L] } #<DATA>,<EA> I J 

Description: Add the source operand to the destination op- 
erand using binary arithmetic. Store the result in the des- 
tination operand. This opcode may be used with any of the I j 

Ippal ADD Vnnarv aHHrpsoino- mnHos TViic nnrnHo Hooc «nt •— ^ 



legal ADD binary addressing modes. This opcode does not 
generate the ADDQ{.[B/W/L] } instruction for those special 
cases. 
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ADDA Instruction 

Action: Add binary address 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: ADDA, ADDA.W, ADDA.L 
Assembler Syntax: 

ADDA{.[W/L] } <EA>,ADST 

Description: Add the source operand to the destination op- 
erand using binary arithmetic. Store the result in the des- 
tination operand. This opcode is a subset of the ADD 
opcode, and requires that the destination be an address 
register. 

ADDI Instruction 

Action: Add binary immediate 
Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: ADDI, ADDI.B, ADDI.W, ADDI.L 
Assembler Syntax: 

ADDIj\[B/W/L] } #<DATA>,<EA> 
Description: Add the source operand to the destination op- 
erand using binary arithmetic. Store the result in the des- 
tination operand. This opcode is a subset of the ADD 
opcode, and requires that the source be an immediate value. 

ADDQ Instruction 

Action: Add binary quick 
Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: ADDQ, ADDQ.B, ADDQ.W, ADDQ.L 
Assembler Syntax: 

ADDQ{.[B/W/L] } #<DATA>,<EA> 
Description: Add the source operand to the destination op- 
erand using binary arithmetic. Store the result in the des- 
tination operand. This opcode requires that the source be an 
immediate value with a data range between one and eight. 

ADDX Instruction 

Action: Add extended 

Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: ADDX, ADDX.B, ADDX.W, ADDX.L 

Assembler Syntax: 

ADDX{.[B/W/L] } DSRCDDST 

ADDX{.[B/W/L] } -(ASRC),-(ADST) 

339 



A d-A U 

Appendix A 

U 

Description: Add the source operand and the extend bit to j j 

the destination operand using binary arithmetic. Store the L — 

result in the destination operand. _ 

U 

AND Instruction 

Action: Logical and I ---. 

Condition Codes: X: - N: * Z: * V: C: | | 

Opcode Forms: AND, AND.B, AND.W, AND.L 
Assembler Syntax: 
AND{.[B/W/L] } <EA>,DDST 
AND{.[B/W/L] } DSRC,<EA> 
AND{.[B/W/L] } #<DATA>,<EA> 
AND{.B} #<DATA>,CCR 

AND{.W} #<DATA>,SR 

Description: Logically AND the source operand to the des- 
tination operand. Store the result in the destination oper- 
and. This opcode may be used with any of the legal AND 
addressing modes. 

ANDI Instruction 

Action: And immediate 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: ANDI, ANDI.B, ANDI.W, ANDI.L 
Assembler Syntax: 

ANDI{.[B/W/L] } #<DATA>,<EA> 
ANDI{.B} #<DATA>,CCR 

ANDlj.W} #<DATA>,SR 

Description: Logically AND the source operand to the des- 
tination operand. Store the result in the destination oper- 
and. This opcode is a subset of the AND opcode, and :" ~ ■, 
requires that the source be an immediate value. I I 



ASL/ASR Instruction 

Action: Arithmetic shift left/right 
Condition Codes: X: * N: * Z: * V: * C: * 



U 
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Opcode Forms: ASL/ASR, ASL.B/ASR.B, ASL.W/ASR.W, I I 

ASL.L/ASR.L * ' — ' 
Assembler Syntax: 

AS[R/L] {.[B/W/L] } DSRCDDST j " I 

AS[R/L] {.[B/W/L] } #<DATA>,DDST L - 1 
AS[R/L] {.W} <EA> 

U 
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Description: Arithmetically shift the destination operand 
left or right N bits. The explicit or implied source operand 
determines N, the number of bits to be shifted. An arithmetic 
shift with an implied shift count, shifts the specified memory 
destination location one bit only, in the specified direction. 

Bcc Instruction 

Action: Branch conditionally 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: Bcc, Bcc.S, Bcc.L 
Assembler Syntax: 
Bcc{.[S/L] } <LABEL> 

Description: Continue program execution at the specified 
label, if the specified condition is met. The .S version of this 
instruction forces an 8-bit displacement to be generated. 
This means that the relative offset of the label must be in 
the range of— 128 to 127 bytes in distance from the current 
program counter. The .L version of this instruction forces an 
16-bit displacement to be generated. This means that the 
relative offset of the label must be in the range of —32768 
to 32767 bytes in distance from the current program 
counter. The current program counter is defined to be the 
current instruction location plus two. If the Bcc instruction is 
used, the assembler automatically decides which of the two 
displacements is most appropriate, and generates that in- 
struction. This is sometimes known as automatic branch 
shortening. 

The following conditions are recognized: 

Condition Signed Meaning Flags Affected 

CC Carry Clear \C 

HS * High or Same \C 

CS Carry Set C 

LO * LOw C 

EQ + EQual Z 

GE + Greater or Equal (N&V) I ( \N& \V) 

GT + Greater Than (N&V&Z) I ( \N& \V& \Z) 

HI * High \C&\Z 

LE + Less or Equal Z I (N& \V) I ( \N&V) 

LS * Low or Same C I Z 

LT + Less Than (N& W) I ( \N&V) 

MI * Minus N 

NE + Not Equal \Z 
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U 

a 

Condition Signed Meaning Flags Affected I i 

u 



PL * PLus \N 

VC overflow Clear \V 

VS overflow Set V 



+ = Signed comparisons 
* = Unsigned comparisons 
\ =NOT 
& = AND 
l = OR 



u 



BRA Instruction 

Action: Branch always 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: BRA, BRA.S, BRA.L 
Assembler Syntax: 

BRA{.[S/L] } <LABEL> 

Description: Continue program execution at the specified 
label. The .S version of this instruction forces an 8-bit dis- 
placement to be generated. This means that the relative off- 
set of the label must be in the range of —128 to 127 bytes 
in distance from the current program counter. The .L ver- 
sion of this instruction forces a 16-bit displacement to be 
generated. This means that the relative offset of the label 
must be in the range of —32768 to 32767 bytes in distance 
from the current program counter. The current program 
counter is defined to be the current instruction location plus 
two. If the BRA instruction is used, the assembler automati- 
cally decides which of the two displacements are most ap- 
propriate, and generates that instruction. This is sometimes \ \ 
known as automatic branch shortening. 

BCHG Instruction I | 

Action: Test a bit and change 

Condition Codes: X: - N: - Z: * V: - C: - i i 

Opcode Forms: BCHG, BCHG.B, BCHG.L I 1 

Assembler Syntax: 

BCHG{.[B/L] } DSRC,<EA> r — , 

BCHG{.[B/L] } #<DATA>,<EA> LJ 
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Description: Place the value of the specified bit, from the 
destination address, in the Z condition code, and then com- 
plement the specified bit in the destination address. If the 
specified destination address is a data register, then the 
specified bit offset is modulo 32. If the specified destination 
address is a memory location, then the specified bit offset is 
modulo 8, and then the offset is applied to the byte location. 

BCLR Instruction 

Action: Test a bit and clear 
Condition Codes: X: - N: - Z: * V: - C: - 
Opcode Forms: BCLR, BCLR.B, BCLR.L 
Assembler Syntax: 

BCLR{.[B/L] } DSRC,<EA> 

BCLR{.[B/L] } #<DATA>,<EA> 

Description: Place the value of the specified bit, from the 
destination address, in the Z condition code, and then clear 
the specified bit in the destination address to 0. If the speci- 
fied destination address is a data register, the specified bit 
offset is modulo 32. If the specified destination address is a 
memory location, the specified bit offset is modulo 8, and 
then the offset is applied to the byte location. 

BSET Instruction 

Action: Test a bit and set 
Condition Codes: X: - N: - Z: * V: - C: - 
Opcode Forms: BSET, BSET.B, BSET.L 
Assembler Syntax: 

BSET{.[B/L] } DSRC,<EA> 

BSET{.[B/L] } #<DATA>,<EA> 

Description: Place the value of the specified bit, from the 
destination address, in the Z condition code, and then set 
the specified bit in the destination address to 1. If the speci- 
fied destination address is a data register, the specified bit 
offset is modulo 32. If the specified destination address is a 
memory location, the specified bit offset is modulo 8, and 
then the offset is applied to the byte location. 
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BSR Instruction 

Action: Branch to subroutine 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: BSR, BSR.S, BSR.L 
Assembler Syntax: 

BSR{.[S/L] } <LABEL> 

Description: The long word address of the instruction im- 
mediately following this instruction is pushed on the stack, 
and program execution then continues at the specified label. 
The .S version of this instruction forces an 8-bit displace- 
ment to be generated. This means that the relative offset of 
the label must be in the range of —128 to 127 bytes in dis- 
tance from the current program counter. The .L version of 
this instruction forces a 16-bit displacement to be generated. 
This means that the relative offset of the label must be in 
the range of —32768 to 32767 bytes in distance from the 
current program counter. The current program counter is 
defined to be the current instruction location plus two. If 
the BSR instruction is used, the assembler automatically de- 
cides which of the two displacements are most appropriate, 
and generates that instruction. This is sometimes known as 
automatic branch shortening. 

BTST Instruction 

Action: Test a bit 

Condition Codes: X: - N: - Z: * V: - C: - 
Opcode Forms: BTST, BTST.B, BTST.L 
Assembler Syntax: 

BTST{.[B/L] } DSRC,<EA> 

BTST{.[B/L]} #<DATA>,<EA> 

Description: Place the value of the specified bit, from the [__j 

destination address, in the Z condition code. If the specified 

destination address is a data register, the specified bit offset 

is modulo 32. If the specified destination address is a mem- [__] 

ory location, the specified bit offset is modulo 8, and then 

the offset is applied to the byte location. 
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CHK Instruction 

Action: Check register against bounds 
Condition Codes: X: - N: * Z: ? V: ? C: ? 
Opcode Forms: CHK, CHK.W 
Assembler Syntax: 

CHK{.W} <EA>,DDST 

Description: The contents of the specified data register are 

compared to the upper bound effective address and 0. If the 

value of the data register is not between and the upper 

bounds, the processor initiates exception processing. The 

CHK instruction vector is used as the address to continue 

processing. 

CLR Instruction 

Action: Clear an operand 
Condition Codes: X: - N: Z: 1 V: C: 
Opcode Forms: CLR, CLR.B, CLR.W, CLR.L 
Assembler Syntax: 

CLR{.[B/W/L] } <EA> 

Description: The specified destination address is cleared to 0. 

CMP Instruction 

Action: Compare 

Condition Codes: X: - N: * Z: * V: * C: * 
Opcode Forms: CMP, CMP.B, CMP.W, CMP.L 
Assembler Syntax: 

CMP{.[B/W/L] } <EA>,DDST 
CMP{.[W/L] } <EA>,ADST 

CMP{.[B/W/L] } #<DATA>,<EA> 
CMP{.[B/W/L] } (ASRC)+,(ADST) + 
Description: Subtract the source operand from the destina- 
tion operand and set the condition codes accordingly. This 
instruction does not modify the destination address. This 
opcode may be used with any of the legal CMP addressing 
modes. 

CMPA Instruction 

Action: Compare address 

Condition Codes: X: - N: * Z: * V: * C: * 

Opcode Forms: CMPA, CMPA.W, CMPA.L 
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Assembler Syntax: 

CMPA{.[W/L] } <EA>,ADST 

Description: Subtract the source operand from the destina- 
tion operand and set the condition codes accordingly. This 
instruction does not modify the destination address. This 
opcode requires that the destination be an address register. 

CMPI Instruction 

Action: Compare immediate 
Condition Codes: X: - N: * Z: * V: * C: * 
Opcode Forms: CMPI, CMPI.B, CMPI.W, CMPI.L 
Assembler Syntax: 

CMPI{.[B/W/L] } #<DATA>,<EA> 
Description: Subtract the source operand from the destina- 
tion operand and set the condition codes accordingly. This 
instruction does not modify the destination address. This 
opcode is a subset of the CMP opcode, and requires the 
source to be an immediate value. 

CMPM Instruction 

Action: Compare memory 

Condition Codes: X: - N: * Z: * V: * C: * 

Opcode Forms: CMPM, CMPM.B, CMPM.W, CMPM.L 

Assembler Syntax: 

CMPM{.[B/W/L] } (ASRC) + ,(ADST) + 
Description: Subtract the source operand from the destina- 
tion operand and set the condition codes accordingly. This 
instruction does not modify the destination address. This 
opcode is a subset of the CMP opcode, and requires that the 
source and destination operands are both indirect with post- 
decrement mode. 
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DB cc Instruction 

Action: Test, decrement, and branch 

Condition Codes: X: - N: - Z: - V: - C: - 

Assembler Syntax: [ ) 

DBcc DSRC,<LABEL> 

Description: If the specified condition is false, decrement 

the destination data register, and then compare the destina- j j 

tion data register with — 1. If the destination data register *~ 

doesn't equal — 1, continue instruction processing at the 
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specified label. If either of the conditions fail, then continue 
instruction execution with the next instruction. This instruc- 
tion uses a 16-bit displacement as a label offset. This means 
that the relative offset of the label must be in the range of 
—32768 to 32767 bytes in distance from the current pro- 
gram counter. 

This instruction provides a primitive looping construct 
similar to the REPEAT UNTIL looping construct of Pascal. 
The DBcc instruction may be thought of as a REPEAT loop 
UNTIL either the condition becomes true, or the loop 
counter goes below 0. This, of course, is assuming that the 
destination data register was initially set to a positive value. 
(This instruction uses the bottom 16 bits of the destination 
data register for a loop counter.) 

On the MC68010 microprocessor, the DBcc instruction 
will go into loop mode when the relative offset of the in- 
struction is —4. This means that any word-length MC68010 
instruction used as the inside part of the loop will run sub- 
stantially faster because the MC68010 will not keep 
refetching the loop instruction and the DBcc instruction. 
This allows for very fast block move routines like the one 
below: 



LEA.L 
LEA.L 

MOVE.W 

i. 


SOURCEADDRESS.A0 

DESTINATI0NADDRESS.A1 

#LENGTHOFMOVE,D0 


M0VE.B 
DBEQ 


(A0)+,(A1) + 
D0,LOOP 



For complete condition codes, see the Bcc instruction. 

DIVS Instruction 

Action: Signed divide 
Condition Codes: X: - N: * Z: * V: * C: 
Opcode Forms: DIVS, DIVS.W 
Assembler Syntax: 
DIVS{.W} * <EA>,DDST 

Description: Divide the source operand by the destination 
operand using a signed divide. Store the result in the des- 
tination operand. The destination operand is expected to be 
a 32-bit value, and the source operand is expected to be a 
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16-bit value. The 16-bit quotient is placed in the lower 16 j | 

bits of the destination operand. The 16-bit remainder is ' — ' 

placed in the upper 16 bits of the destination operand. Divi- 
sion by zero will cause a processor trap. If overflow is set, 
the operands remain unaffected. 



EORI Instruction 

Action: Exclusive OR Logical Immediate 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: EORI, EORI.B, EORI.W, EORI.L 
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DIVU Instruction j | 

Action: Unsigned divide 
Condition Codes: X: - N: * Z: * V: * C: 
Opcode Forms: DIVU, DIVU.W 
Assembler Syntax: 

DIVU{.W} <EA>,DDST 

Description: Divide the source operand by the destination 
operand using an unsigned divide. Store the result in the 
destination operand. The destination operand is expected to 
be a 32-bit value, and the source operand is expected to be 
a 16-bit value. The 16-bit quotient is placed in the lower 16 
bits of the destination operand. The 16-bit remainder is 
placed in the upper 16 bits of the destination operand. Divi- 
sion by zero will cause a processor trap. If overflow is set, 
the operands remain unaffected. 

EOR Instruction 

Action: Exclusive OR Logical 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: EOR, EOR.B, EOR.W, EOR.L 
Assembler Syntax: 

EOR{.[B/W/L] } DSRC,<EA> 

EOR{.[B/W/L] } #<DATA>,<EA> 

EOR{.B} #<DATA>,CCR , - , 

EOR{.W} #<DATA>,SR \ | 

Description: Exclusive OR the source operand to the des- 
tination operand. Store the result in the destination oper- ( , 

and. This opcode may be used with any of the legal EOR | J 

addressing modes. 
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P"l Assembler Syntax: 

i ! EORI{.[B/W/L] } #<DATA>,<EA> 
EORI{.B} #<DATA> / CCR 

(— J EORI{.W} #<DATA>,SR 

1 i Description: Exclusive OR the source operand to the des- 
tination operand. Store the result in the destination oper- 

(~~| and. This opcode is a subset of the EOR opcode, and 

I i requires that the source be an immediate value. 

EXG Instruction 

Action: Exchange registers 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: EXG 

Assembler Syntax: 

EXG{.L} RSRQRDST 

Description: Exchange the contents of source and destina- 
tion registers. All 32-bits are always exchanged. Any two 
registers may be specified. 

EXT Instruction 

Action: Sign Extend 

Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: EXT, EXT.W, EXT.L 
Assembler Syntax: 

EXT{.[W/L] } DSRC 

Description: Extend the sign bit of a register from an 8-bit 
value to a 16-bit value, EXT.W, or from a 16-bit value to a 
32-bit value, EXT.L. If the instruction EXT.W is used, then 
bit 7 is copied into bits 8-15. If the instruction EXT.L is 

p— n used, then bit 15 is copied into bits 16-31. 

i i 

ILLEGAL Instruction 

(""""I Action: Take Illegal Instruction Trap 
' I Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: ILLEGAL 

n Assembler Syntax: 
ILLEGAL 

Description: This instruction will always generate an illegal 
r~*| instruction exception. 



349 



Appendix A 



U 
D 



U 



U 



JMP Instruction 

Action: Jump 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: JMP j ] 

Assembler Syntax: I — i 

JMP ' <EA> 

Description: Continue program execution at the new ad- 
dress specified by the instruction. 

JSR Instruction 

Action: Jump to subroutine 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: JSR 

Assembler Syntax: 

JSR <EA> 

Description: Push the long-word address of the instruction 

immediately following the JSR instruction onto the stack, 

and then continue program execution at the new address 

specified by the instruction. 

LEA Instruction 

Action: Load effective address 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: LEA, LEA.L 

Assembler Syntax: 

LEA{.L} <EA>,ADST 

Description: Load the calculated (effective) address into the 

destination address register. 
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LINK Instruction 

Action: Link and allocate I — J 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: LINK, LINK.W 
Assembler Syntax: 

LINK{.W} " ADST,#<DISPLACEMENT> 

Description: Push the current contents of the destination 
address register onto the stack. Load the contents of the 
stack pointer into the destination address register. Add the 
immediate value to the stack pointer. 

This instruction is commonly used at subroutine entry 
to allocate a new frame pointer and local temporary storage. 
This is normally done with a negative displacement. 
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I — i LSL/LSR Instruction 

! I Action: Logical shift left/right 

Condition Codes: X: * N: * Z: * V: C: * 

[—"l Opcode Forms: LSL/LSR, LSL.B/LSR.B, LSL.W/LSR.W, 

1 I LSL.L/LSR.L 

Assembler Syntax: 

I — | LS[LR] {.[B/W/L] } DSRCDDST 

i > LS[LR] {.[B/W/L] } #<DATA>,DDST 

LS[LR] {.W} <EA> 

Description: Logically shift the destination operand left or 
right N bits. The explicit or implied source operand deter- 
mines N, the number of bits to be shifted. A logical shift 
with an implied shift count, shifts the specified memory 
destination location one bit only, in the specified direction. 

MOVE Instruction 

Action: Move data 

Condition Codes: X: - N: * Z: * V: C: 

Opcode Forms: MOVE, MOVE.B, MOVE.W, MOVE.L 

Assembler Syntax: 

MOVE{.[B/W/L] } <EA>,<EA> 
MOVE{.[W/L] } <EA>,ADST 

MOVE{.W} <EA>,CCR 

MOVE{.W} <EA>,SR 

MOVE{.W} SR,<EA> 

MOVE{.L} ASRCUSP 

MOVEJ.L} USP,ADST 

Description: Copy the source operand to the destination 
operand. The upper byte of data is ignored when moving 
data to the condition code register. The move instructions 
r """] that load and store the user stack pointer from and to an 

' address register may only be executed while in supervisor 

mode. On the 68010 microprocessor, the move instructions 
that load and store the status register may only be executed 
while in supervisor mode. 

MOVEA Instruction 

Action: Move address 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: MOVEA, MOVEA. W, MOVEA.L 



351 



Appendix A 



U 

U 

Assembler Syntax: , -, 

MOVEA{.[W/L] } <EA>,ADST | | 

Description: Copy the source operand to the destination 

operand. This opcode is a subset of the MOVE opcode, and , 

requires that the destination be an address register. If the |_ J 
value is loaded as a 16-bit word value, this value is auto- 
matically sign-extended. 



U 



MOVEC Instruction 

Action: Move control register (MC68010/MC68020) 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: MOVEC, MOVEC.L 
Assembler Syntax: 

MOVE{.L} RSRCSFC 

MOVE{.L} RSRCDFC 

MOVE{.L} RSRCUSP 

MOVE{.L} RSRCVBR 

MOVEj.L} SFCRDST 

MOVE{.L} DFCRDST 

MOVE{.L} USP,RDST 

MOVE{.L} VBR,RDST 

Description: Copy the source operand to the destination 
operand. This instruction is used to load and store the vari- 
ous control registers that exist on the MC68010 and the 
MC68020. The RSRC and RDST registers may be any 32-bit 
address or data register. This instruction is privileged, and 
may only be executed in supervisor mode. The following is 
the list of the special registers available on the MC68010. 

Special Register Full Name 

SFC Source Function Register 

DFC Destination Function Register j j 

USP User Stack Pointer ' — ' 

VBR Vector Base Register 

u 

MOVEM Instruction 

Action: Move multiple registers I i 

Condition Codes: X: ^ N: - Z: - V: - C: - I I 

Opcode Forms: MOVEM, MOVEM.W, MOVEM.L 

Assembler Syntax: I , 

MOVEM{.[W/L] } <REGISTER LIST>,<EA> U 
MOVEM{.[W/L] } <EA>,<REGISTER LIST> 
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[~~| Description: Transfer the selected registers from the register 

list to or from the consecutive memory locations starting at 
the memory location specified by the effective address. The 

!"**"] register list is evaluated to a mask that specifies the list of 

' registers to be transferred. 

! | MOVEP Instruction 

Action: Move peripheral data 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: MOVEP, MOVEP. W, MOVEP.L 
Assembler Syntax: 
MOVEP{.[W/L] } DSRC,X(AN) 
MOVEP{.[W/L] } X(AN),DDST 
Description: Copy the source operand to the destination 
operand. This instruction transfers data in alternate bytes to 
or from memory. The starting address is specified by the 
displacement of the specified address register, and the re- 
maining addresses are specified by incrementing the transfer 
location by two. This instruction is designed to facilitate the 
transfer of data between 8-bit devices and the 16-bit data bus. 

MOVES Instruction 

Action: Move address space (MC68010/MC68020) 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: MOVES, MOVES.B, MOVES.W, MOVES.L 
Assembler Syntax: 

MOVES{.[B/W/L] } RN,<EA> 
MOVES {.[B/W/L] } <EA>,RN 

Description: Copy the source operand to the destination 
operand. This instruction uses the SFC or DFC registers to 
generate the necessary function code values to the function 
code pins of the MC68010 and MC68020 chips when the 
data is being transferred. The SFC register is used when the 
data is being transferred to the general purpose register, and 
the DFC register is used when the data is being transferred 
to a memory location. 
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NBCD Instruction 

Action: Negate decimal with extend 
Condition Codes: X: * N: ? Z: * V: ? C: * 
Opcode Forms: NBCD 
Assembler Syntax: 

NBCD ' <EA> 
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MOVEQ Instruction j j 

Action: Move quick ' — ' 

Condition Codes: X: - N: * Z: * V: C: 

Opcode Forms: MOVEQ, MOVEQ.L j j 

Assembler Syntax: ' — ' 

MOVEQ{.L} #<DATA>,DDST 

Description: Copy the source operand to the destination j I 

operand. This opcode requires that the source be an 8-bit * — ' 

immediate value. The immediate value is sign-extended 

before loading it as a 32-bit number into the specified data 

register. 

MULS Instruction 

Action: Signed multiply 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: MULS, MULS.W 
Assembler Syntax: 

MULS{.W} " <EA>,DDST 

Description: Multiply the source operand and the destina- 
tion operand generating a signed value. Store the result in 
the destination operand. Both operands are expected to be 
16-bit values, and the destination operand receives a 32-bit 
result. 

MULU Instruction 

Action: Unsigned multiply 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: MULU, MULU.W 
Assembler Syntax: 

MULU{.W} <EA>,DDST 

Description: Multiply the source operand and the destina- 
tion operand generating an unsigned value. Store the result 
in the destination operand. Both operands are expected to Y ~"i 

be 16-bit values, and the destination operand receives a 32- I I 

bit result. 
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Description: Subtract the destination operand and the ex- 
tend bit from zero, and store the result back in the destina- 
tion location. This produces a tens complement if the extend 
bit is 0, a nines complement if it is set. This is a byte opera- 
tion only. 

NEG Instruction 

Action: Negate 

Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: NEG, NEG.B, NEG.W, NEG.L 

Assembler Syntax: 

NEG{.[B/W/L] } <EA> 

Description: The destination operand is subtracted from 

zero, and the result is placed back in the destination 

location. 

NEGX Instruction 

Action: Negate with extend 

Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: NEGX, NEGX.B, NEGX.W, NEGX.L 

Assembler Syntax: 

NEGX{.[B/W/L] } <EA> 

Description: The destination operand and the extend bit are 

subtracted from zero, and the result is placed back in the 

destination location. 

NOP Instruction 

Action: No operation 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: NOP 

Assembler Syntax: 

NOP 

Description: This instruction does not affect the processor 
state other than to update the program counter to continue 
execution at the next instruction. 

NOT Instruction 

Action: Logical complement 

Condition Codes: X: - N: * Z: * V: C: 

Opcode Forms: NOT, NOT.B, NOT.W, NOT.L 
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Assembler Syntax: { I 

NOT{.[B/W/L] } <EA> UJ 

Description: The ones complement of the destination oper- 
and is calculated and placed back in the destination j j 
location. 

OR Instruction LJ 

Action: Logical inclusive OR 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: OR, OR.B, OR.W, OR.L 
Assembler Syntax: 
OR{.[B/W/L] } <EA>,DDST 

OR{.[B/W/L] } DSRC,<EA> 

OR{.[B/W/L] } #<DATA>,<EA> 

OR{.B} #<DATA>,CCR 

OR{.W} #<DATA> / SR 

Description: Inclusive OR the source operand to the des- 
tination operand. Store the result in the destination oper- 
and. This opcode may be used with any of the legal OR 
addressing modes. 

ORI Instruction 

Action: Logical immediate inclusive OR 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: ORI, ORI.B, ORI.W, ORI.L 
Assembler Syntax: 

ORI{.[B/W/L] } #<DATA>,<EA> 

ORlj.B} #<DATA>,CCR 

ORI{.W} #<DATA>,SR 

Description: Inclusive OR the source operand to the des- 
tination operand. Store the result in the destination oper- 
and. This opcode is a subset of the OR opcode and requires 
that the source be an immediate value. 



PEA Instruction 
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Action: Push effective address j j 

Condition Codes: X: - N: - Z: - V: - C: - — 

Opcode Forms: PEA, PEA.L 

Assembler Syntax: 1 j 

PEA{.L} <EA> UJ 

Description: Push the calculated (effective) address onto the 

stack. 
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RESET Instruction 

Action: Reset external devices 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: RESET 

Assembler Syntax: 

RESET 

Description: The reset line on the processor is asserted, 
causing all external devices to be reset. This instruction does 
not affect the processor state other than to update the pro- 
gram counter to continue execution at the next instruction. 

ROL/ROR Instruction 

Action: Rotate left/right 

Condition Codes: X: - N: * Z: * V: C: * 

Opcode Forms: ROL/ROR, ROL.B/ROR.B, 

ROL.W/ROR.W, ROL.L/ROR.L 

Assembler Syntax: 

RO[LR] {.[B/W/L] } DSRCDDST 

RO[LR] {.[B/W/L] } #<DATA>,DDST 

RO[LR] {.[B/W/L] } <EA> 

Description: Rotate the destination operand left or right N 

bits. The explicit or implied source operand determines N, 

the number of bits to be rotated. A rotate with an implied 

shift count rotates the specified memory destination location 

one bit only, in the specified direction. 

ROXL/ROXR Instruction 

Action: Rotate left/right with extend 
Condition Codes: X: * N: * Z: * V: C: » 
Opcode Forms: ROXL/ROXR, ROXL.B/ROXR.B, 
ROXL.W/ROXR.W, ROXL.L/ROXR.L 
Assembler Syntax: 
ROX[L/R] {.[B/W/L] } DSRCDDST 
ROX[L/R] {.[B/W/L] } #<DATA>,DDST 
ROX[L/R] {.[B/W/L] } <EA> 

Description: Rotate the destination operand left or right N 
bits. The extend bit is included as part of the rotation. The 
explicit or implied source operand determines N, the num- 
ber of bits to be rotated. A rotate with an implied shift 
count rotates the specified memory destination location one 
bit only, in the specified direction. 



357 



Appendix A 



U 

u 

RTE Instruction [_J 

Action: Return from exception 
Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: RTE j j 

Assembler Syntax: 
RTE 

Description: Load the exception state information from the I | 

top of stack and continue with execution. This instruction "" 

reloads the status register stack pointer and program counter 
in the appropriate manner for the chip, and continues exe- 
cution at the old program counter address. It should be 
noted that this function, although similar for both the 
MC68000 and the MC68010, is different because the excep- 
tion frames are organized differently for the two processors. 

RTD Instruction 

Action: Return and deallocate 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: RTD (MC68010/MC68020) 
Assembler Syntax: 

RTD #<DISPLACEMENT> 

Description: Load the old program counter from the stack 
and then add the 16-bit displacement, which has been sign 
extended to 32-bits, to the stack pointer. Proceed to execute 
the next instruction at the updated program location. The 
displacement field is a twos complement value. 
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RTR Instruction 

Action: Return and restore condition codes 

Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: RTR 

Assembler Syntax: 

RTR 

Description: Load the condition code and a new program 

counter from the stack. Proceed with execution at the new 

program counter address. j j 

RTS Instruction 

Action: Return from subroutine 11 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: RTS 
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Assembler Syntax: 

RTS 

Description: Load a new program counter from the top of 

the stack, and proceed with execution at this new address. 

SBCD Instruction 

Action: Subtract decimal with extend 
Condition Codes: X: * N: ? Z: * V: ? C: * 
Opcode Forms: SBCD 
Assembler Syntax: 
SBCD DSRCDDST 

SBCD -(ASRC),-(ADST) 

Description: Subtract the source operand from the destina- 
tion operand using binary coded decimal (BCD) arithmetic. 
Store the result in the destination operand. 

Sec Instruction 

Action: Set according to condition codes 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: Sec 

Assembler Syntax: 

Sec <EA> 

Description: Set the specified byte address to OxFF if the 

condition is met, or to 0x00 if the condition is not met. For a 

complete list of valid condition codes, see the Bcc instruction. 

STOP Instruction 

Action: Load status register and stop 
Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: STOP 
Assembler Syntax: 

STOP #<DATA> 

Description: Load the immediate data into the status regis- 
ter, advance the program counter to the next instruction, 
and make the microprocessor pause. The processor resumes 
executing instructions when a trace, interrupt, or reset ex- 
ception is initiated. If an interrupt request arrives whose pri- 
ority is higher than the current processor priority, an 
interrupt exception occurs; otherwise, the interrupt request 
has no effect. 
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SUB Instruction ! I 

Action: Subtract binary 
Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: SUB, SUB.B, SUB.W, SUB.L | j 

Assembler Syntax: 
SUB{.[B/W/L] } <EA>,DDST 

SUB{.[B/W/L] } DSRC,<EA> ) j 

SUB{.[W/L] } <EA>,ADST 

SUB{.[B/W/L] } #<DATA>,<EA> 

Description: Subtract the source operand from the destina- 
tion operand using binary arithmetic. Store the result in the 
destination operand. This opcode may be used with any of 
the legal SUB addressing modes. This opcode does not gen- 
erate the SUBQ{.[B/W/L] } instruction for those special 
cases. 

SUBA Instruction 

Action: Subtract binary addresses 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: SUBA, SUBA.W, SUBA.L 
Assembler Syntax: 

SUBA{.[W/L] } <EA>,ADST 

Description: Subtract the source operand from the destina- 
tion operand using binary arithmetic. Store the result in the 
destination operand. This opcode is a subset of the SUB 
opcode, and requires that the destination be an address 
register. 

SUBI Instruction 

Action: Subtract binary immediate 
Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: SUBI, SUBI.B, SUBI.W, SUBI.L 
Assembler Syntax: 

SUBI{ ; [B/W/L] } #<DATA>,<EA> 
Description: Subtract the source operand from the destina- 
tion operand using binary arithmetic. Store the result in th': 
destination operand. This opcode is a subset of the SUB 
opcode, and it requires that the source be an immediate 
value. 
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SUBQ Instruction 

Action: Subtract binary quick 
Condition Codes: X: * N: * Z: * V: * C: * 
Opcode Forms: SUBQ, SUBQ.B, SUBQ.W, SUBQ.L 
Assembler Syntax: 

SUBQ{.[B/W/L] } #<DATA>,<EA> 
Description: Subtract the source operand from the destina- 
tion operand using binary arithmetic. Store the result in the 
destination operand. This opcode requires that the source be 
an immediate value with a data range of 1-8. 

SUBX Instruction 

Action: Subtract binary with extend 

Condition Codes: X: * N: * Z: * V: * C: * 

Opcode Forms: SUBX, SUBX.B, SUBX.W, SUBX.L 

Assembler Syntax: 

SUBX{.[B/W/L] } DSRCDDST 

SUBX{.[B/W/L] } -(ASRC),-(ADST) 

Description: Subtract the source operand and the extend bit 

from the destination operand using binary arithmetic. Store 

the result in the destination operand. 

SWAP Instruction 

Action: Swap register halves 
Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: SWAP, SWAP.W 
Assembler Syntax: 

SWAP{.W} DDST 

Description: Exchange the upper 16 bits of the destination 
data register with the lower 16 bits of the same register. 
Store the result in the destination data register. 

TAS Instruction 

Action: Test and set 

Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: TAS, TAS.B 
Assembler Syntax: 

TAS{.B} <EA> 
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Description: Test the byte address specified in the destina- j 
tion, and set the N and Z condition codes appropriately. Set — 
the high order bit of the operand. These operations are per- 
formed using read-modify-write memory cycles and are j j 
guaranteed indivisible operations. This instruction is useful — 

for synchronization between multiple processors. 

i I 

TST Instruction 

Action: Test 

Condition Codes: X: - N: * Z: * V: C: 
Opcode Forms: TST, TST.B, TST.W, TST.L 
Assembler Syntax: 

TST{.[B/W/L] } <EA> 

Description: Compare the specified operand to zero, and 

set the condition codes. The destination address is left 

unmodified. 

UNLK Instruction 

Action: Unlink 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: UNLK 

Assembler Syntax: 

UNLK ADST 

Description: Load the stack pointer from the destination 
address register, then pop the long value from the new top 
of the stack and place it in the destination register. This in- 
struction is commonly used at subroutine exit to restore an 
old frame pointer and free up any local temporary storage. 

Pseudo-ops I I 

ALIGN Pseudo-op | I 

Action: Align the program counter to any boundary 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: ALIGN I J 

Assembler Syntax: 

ALIGN <VALUE> 
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Description: This directive aligns the current section on a 
modulo <value> boundary. Zero to <^LUE> — 1 bytes 
of zero data will be generated to properly change the align- 
ment as requested. This pseudo-op allows the user to align 
the instruction counter on any boundary. The following ex- 
ample aligns the instruction counter on a four-word boundary: 

ALIGN 4 

This is equivalent to the following CNOP pseudo-op: 

CNOP 0,4 

ASCII Pseudo-op 

Action: Define a constant string 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: ASCII 

Assembler Syntax: 

ASCII <STRING> 

Description: This pseudo-op generates a series of bytes of 
data the same length as the specified string. The generated 
data is a set of bytes whose ASCII values are represented by 
the characters in the string. This series of bytes is not null- 
terminated. 

ASCIZ Pseudo-op 

Action: Define a constant null-terminated string 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: ASCIZ 
Assembler Syntax: 
ASCIZ <STRING> 

Description: This pseudo-op generates a series of bytes of 
data one byte longer than the specified string. The gener- 
ated data is a set of bytes whose ASCII values are repre- 
sented by the characters in the string. A null-termination 
character is generated with this directive. 

CNOP Pseudo-op 

Action: Conditional no operation 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: CNOP 
Assembler Syntax: 

CNOP <VALUE> / <VALUE> 
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Description: This pseudo-op aligns the instruction counter 
to a boundary. The first expression <VALUE> specifies the ~~ J 

amount to increase the instruction counter after the instruc- 
tion counter has been moved to the proper alignment 
boundary. The second expression <\fi\LUE> specifies the J 

alignment boundary to be used. The following example 
aligns the instruction counter one byte after the nearest j I 

eight-byte boundary: 

CNOP 1,8 

COMM Pseudo-op 

Action: Define a common storage/BSS (Block Storage Sec- 
tion) block 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: COMM 
Assembler Syntax: 

COMM <LABEL>,<VALUE> 

Description: This directive places the given symbol <LA- 
BEL> into the BSS section with a size of <VALUE> bytes 
long. 

DC Pseudo-op 

Action: Define constant 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: DC, DC.B, DC.W, DC.L 
Assembler Syntax: 

DC{.[B/W/L] } <VALUE>{,<VALUE>. . .} 

Description: This pseudo-op generates constant values 

specified in the arguments into the object module so that 

they may be placed in memory at the specified instruction j | 

counter locations at the start of program execution. All data 

values are treated as 32-bit signed values. These values are 

truncated when necessary, as determined by the size sped- j 

fier for the pseudo-op. The assembler automatically aligns '""**"" 

the current program counter to an even boundary if the 

specified constant is either a word or a long-word value, | ! 

and the current program counter is on an odd boundary. L ~~ J 
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DCB Pseudo-op 

Action: Define constant block 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: DCB.W, DCB.L 

Assembler Syntax: 

DCB{.[B/W/L] } <EXP1>,<EXP2> 

Description: This pseudo-op generates <EXP1> number of 
memory locations in the object module. These memory lo- 
cations contain the value specified in <EXP2>. The 
<EXP2> value is treated as a 32-bit signed value that's 
truncated when necessary, as determined by the size speci- 
fier for the pseudo-op. 

DS Pseudo-op 

Action: Define storage 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: DS, DS.B, DS.W, DS.L 
Assembler Syntax: 

DS{.[B/W/L] } <VALUE> 

Description: This pseudo-op allocates the specified number 
of memory locations into the object module. When a DS 
pseudo-op is used and the current section is either a text or 
data section, the DS pseudo-op forces the allocated bytes to 
contain a value. This assembler automatically aligns the 
current program counter to an even boundary if the speci- 
fied storage is either a word or a long-word value, and the 
current program counter is on an odd boundary. One 
method of aligning the program counter to an even bound- 
ary is to generate the line: 

DS.W 

Other alignment methods include using the EVEN, 
ALIGN, and CNOP pseudo-ops. 



ELSE Pseudo-op 

Action: Reverse current conditional assembly condition 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: ELSE 
Assembler Syntax: 

ELSE 
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Description: This pseudo-op changes the true/false condi- \ 

tion of the currently active IF pseudo-op. This pseudo-op u ™ 

does not have arguments. ELSE pseudo-ops may be nested 
just like other IFxx pseudo-ops. When ELSE pseudo-ops are | 
nested, the current ELSE pertains to the most recent IF 
pseudo-op. For example: 



IFEQ 


1 


ADDQ.L 


#1,D0 


ELSE 




MOVEQ 


#0,D0 


ENDC 





will assemble the MOVEQ instruction. 

END Pseudo-op 

Action: End of program 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: END 
Assembler Syntax: 
END 

Description: This statement is currently optional. Its pur- 
pose is to specify the last line of an assembly file. All source 
code statements following this line will be ignored. 

ENDC Pseudo-op 

Action: End conditional assembly 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: ENDC 
Assembler Syntax: 

ENDC * , - 

Description: This pseudo-op terminates the current nesting ( | 

level of conditional assembly. This pseudo-op may be used 
with any of the conditional IF pseudo-ops. 



ENDM Pseudo-op 
Action: End macro definition 
Condition Codes: X: - N: - Z: 
Opcode Forms: ENDM 
Assembler Syntax: 
ENDM 
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Description: This pseudo-op signals the assembler to termi- 
nate the current macro definition. After this pseudo-op is 
processed, the assembler returns to normal input line 
processing. 

EVEN Pseudo-op 

Action: Align the program counter to an even boundary 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: EVEN 
Assembler Syntax: 

EVEN 

Description: This directive aligns the current section on an 
even boundary by generating one byte of data, if necessary, 
or no data if the current section is already aligned. 

FAIL Pseudo-op 

Action: Generate a user error 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: FAIL 

Assembler Syntax: 

FAIL 

Description: This pseudo-op tells the assembler to flag a 

user error on this assembly statement. 

FORMAT Pseudo-op 

Action: No action taken 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: FORMAT 

Assembler Syntax: 

FORMAT 

Description: This pseudo-op is currently parsed and ac- 
cepted by the assembler, but totally ignored. 

GLOBAL Pseudo-op 

Action: Set a label to be externally defined 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: GLOBAL, GLOBL, XDEF 
Assembler Syntax: 

GLOBAL <LABEL>{,<LABEL>. . .} 

GLOBL <LABEL>{,<LABEL>. . .} 

XDEF <LABEL>{,<LABEL>. . .} 
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Description: This pseudo-op sets the specified list of labels i J 
to become globally-defined labels. This assembler lifts the 

restriction that these labels must be defined in the current , - ■•-, 

file. Instead, this pseudo-op is kept for backward capability l^j 
and is used as a flag, to the assembler, that the label names, 

which are listed as arguments, are globally defined symbols , . 

that exist in the current assembly. The XDEF, GLOBL, and [ ! 

GLOBAL pseudo-ops are kept for compatibility with other 
assembly language formats. 

IDNT Pseudo-op 

Action: Name program unit 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: IDNT 

Assembler Syntax: 

IDNT <STRING> 

Description: This pseudo-op sets the name of the program 

unit. By default a program unit has no name, which is 

equivalent to using this pseudo-op with a null string. An 

IDNT pseudb-op is not required for proper functioning of 

the program or the assembler, but is provided for reasons of 

compatibility. 

IFxv Pseudo-op 

Action: Control conditional assembly 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: IFEQ, IFNE, IFGT, IFGE, IFLT, IFLE 

Assembler Syntax: 

IFEQ <VALUE> 

IFNE <VALUE> 

IFGT <VALUE> 

IFGE <VALUE> 

IFLT <VALUE> 

IFLE <VALUE> 
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Description: These pseudo-ops, depending on the value of 
the expression and the pseudo-op used, enable or disable 
assembly. If the condition of the expression is false, assem- 
bly of the input stream will be disabled until a balancing 
ENDC pseudo-op is detected. IF conditionals may be 
nested. The current nesting level is 16 deep. The appropri- 
ate number of nested ENDC pseudo-ops must be reached 
before the assembler will continue processing statements. 
See also the ELSE conditional for reversing the current 
enable/disable assembly level. As an example: 

IFEQ 3 
MOVEQ #0,D0 
ENDC 

will not assemble the MOVEQ instruction. 

IFC/IFNC Pseudo-op 

Action: Assemble with respect to string comparison 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: IFC, IFNC 
Assembler Syntax: 

IFC <STRING>,<STRING> 

IFNC <STRING>,<STRING> 

Description: These pseudo-ops will enable or disable as- 
sembly depending on the equality or inequality of the two 
strings. If the condition of the string comparison evaluates 
to false, assembly of the input stream will be disabled until 
a balancing ENDC pseudo-op is detected. IF conditionals 
may be nested. The current nesting level is 16 deep. The 
appropriate number of nested ENDC pseudo-ops must be 
reached before the assembler will continue processing state- 
ments. See also the ELSE conditional for reversing the cur- 
rent enable/disable assembly level. As an example: 

IFC 'F007BAR' 

MOVEQ #0,D0 
ENDC 

will not assemble the MOVEQ instruction. 
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IFD/IFND Pseudo-op [_] 

Action: Assemble with respect to defined/undefined label 
Condition Codes: X: - N: - Z: - V: - C: - r~- 1 

Opcode Forms: IFD, IFND LJ 

Assembler Syntax: 

IFD <SYMBOL> , ■ -■ 

IFND <SYMBOL> LJ 

Description: Depending on whether the specified symbol is 
defined or undefined, these pseudo-ops will enable or dis- 
able assembly. If these conditionals evaluate to false, then 
assembly of the input stream will be disabled until a balanc- 
ing ENDC pseudo-op is detected. These IF conditionals may 
be nested. The current nesting level is 16 deep. The appro- 
priate number of nested ENDC statements must be reached 
before the assembler will continue processing statements. 
See also the ELSE conditional for reversing the current 
enable/disable assembly level. As an example: 

IFND MAIN 
MOVEQ #0,D0 
ENDC 

will not assemble the MOVEQ instruction if the symbol MAIN 
is defined. 

INCLUDE Pseudo-op 

Action: Include an external file 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: INCLUDE 

Assembler Syntax: 

INCLUDE <FILENAME> 

Description: This pseudo-op notifies the assembler that the 

current input stream should now be extracted from the 

named file, until either further notice from another IN- > > 

CLUDE statement, or until the end of the named input file. |_J 

This capability allows the programmer to cleanly sepa- 
rate definitions or common code from program specific de- . -j 
tails. Some uses of this pseudo-op are including header files [^j 
of common definitions, including header files of common 
macros, and including program specific code into the middle , , 
of machine-independent startup files. L^J 

The assembler will search for the include file in both 
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the current directory as well as the specified include list de- 
noted by the -i flag. INCLUDE pseudo-ops may be nested a 
maximum of eight deep with this release of the ASM68010 
assembler. 

LIST Pseudo-op 

Action: Turn on listing 

Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: LIST 
Assembler Syntax: 
LIST 

Description: This pseudo-op tells the assembler to continue 
listing from this point onward. This pseudo-op does not ap- 
pear in the listing file. 

LLEN Pseudo-op 

Action: Set line length 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: LLEN 

Assembler Syntax: 

LLEN <VALUE> 

Description: This pseudo-op sets the length of the output 
line sent to the listing file. This pseudo-op expects a value, 
which represents the number of characters in the line (be- 
tween 60 and 132). The default value for this pseudo-op is 
80 characters. This pseudo-op does not appear in the listing 
file. 

MACRO Pseudo-op 

Action: Define a macro 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: MACRO 

Assembler Syntax: 

LABEL MACRO 

Description: This pseudo-op starts a macro definition. This 
pseudo-op tells the assembler to absorb input lines until an 
ENDM pseudo-op is encountered. The ENDM pseudo-op 
tells the assembler that the macro definition is completed. 
The next time the assembler sees the label given to the 
macro, it will insert the contents of the absorbed lines into 
the input stream. These lines will at that time be processed 
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by the assembler. The absorbed lines may contain any regu- | 
lar input line or macro calls; however, they may not contain ^ 
other macro definitions. - . 

The backslash symbol has special meaning when the j j 

assembler is reprocessing lines that have been generated as "^^ 
the result of an instance of a macro label. Whenever the as- . _. 
sembler parses a number preceded by a backslash, (such as j | 
\ 1 or \ 6), the assembler substitutes these characters with ^ 
the corresponding argument in the macro expansion (the 
first and sixth in this example). For example, if the assem- 
bler sees a \ 6, then it will replace these two characters 
with the sixth argument to the macro call. If this argument 
does not exist, then the assembler simply removes these 
two characters. 

The second special sequence is \@. Whenever an \@ 
is found in the input line during a macro expansion, it will 
automatically be replaced with a .n, where n is a unique 
number. These numbers are generated by incrementing a 
counter every time this combination of characters is found 
in a macro expansion. This is normally used to generate 
unique labels in a macro. Macro calls may be nested as 
many as 16 deep. There is also an upper limit to the num- 
ber of arguments in a macro call. This upper limit is cur- 
rently set to 24 arguments. 

MASK2 Pseudo-op 

Action: No action taken 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: MASK2 

Assembler Syntax: I , 

MASK2 U 

Description: This pseudo-op is currently parsed and ac- 
cepted by the assembler, but totally ignored. , , 

MEXIT Pseudo-op 

Action: Exit from macro expansion j 

Condition Codes: X: - N: - Z: - V: - C: - UJ 
Opcode Forms: MEXIT 

Assembler Syntax: I 

MEXIT UJ 
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Description: When this macro is invoked during a macro 
expansion it signals the assembler to stop expanding the 
current macro. This macro is most commonly embedded 
within condition statements inside macro definitions. 

NARG Pseudo-op 

Action: Special symbol name 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: NARG 

Assembler Syntax: 

NARG 

narg 

Description: NARG contains the number of arguments 

passed to a macro expansion. 

NOFORMAT Pseudo-op 

Action: No action taken 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: NOFORMAT 

Assembler Syntax: 

NOFORMAT 

Description: This pseudo-op is currently parsed and ac- 
cepted by the assembler, but totally ignored. 

NOLIST Pseudo-op 

Action: Turn off listing 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: NOLIST, NOL 

Assembler Syntax: 

NOLIST 

NOL 

Description: These pseudo-ops tell the assembler to halt 

listing output from this point onward. This directive does 

not appear in the listing file. 

NOOBJ Pseudo-op 

Action: Disable object code generation 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: NOOBJ 
Assembler Syntax: 
NOOBJ 
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Description: This statement flags the assembler not to gen- j 
erate any object code. '■ — ' 

NOPAGE Pseudo-op [J 

Action: Disable page header generation 

Condition Codes: X: - N: - Z: - V: - C: - . 

Opcode Forms: NOPAGE |J 

Assembler Syntax: 
NOPAGE 

Description: This pseudo-op turns off paging capability. 
This forces the assembler to generate a listing file without 
headers, footers, and other page numbering information, 
when the listing option is enabled. This pseudo-op does not 
appear in the listing file. 

OFFSET Pseudo-op 

Action: Define offsets 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: OFFSET 

Assembler Syntax: 

OFFSET <VALUE> 

Description: This pseudo-op is currently parsed and ac- 
cepted by the ASM68010 assembler, but totally ignored. 

PAGE Pseudo-op 

Action: Enable page header generation 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: PAGE 
Assembler Syntax: 

PAGE 

Description: This pseudo-op reenables the paging feature of 
listing output. This option is turned on by default every 
time the listing option of the assembler has been enabled. 
When this option is enabled, the assembler listing file will 
contain headers and footers around each page break. This 
pseudo-op does not appear in the listing file. 

PLEN Pseudo-op 

Action: Set page length 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: PLEN 
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Assembler Syntax: 

PLEN <VALUE> 

Description: This pseudo-op sets the length of an output 
page sent to the listing file. This pseudo-op expects a value, 
which represents the number of lines in a page (between 24 
and 100). The default value for this pseudo-op is 66 lines. 
This pseudo-op does not appear in the listing file. 

REG Pseudo-op 

Action: Set register list 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: REG 

Assembler Syntax: 

REG _ <VALUE> 

Description: This pseudo-op is currently parsed and ac- 
cepted by the assembler, but totally ignored. 

RORG Pseudo-op 

Action: Set relative origin 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: RORG 
Assembler Syntax: 
RORG <VALUE> 

Description: This pseudo-op is currently parsed and ac- 
cepted by the assembler, but totally ignored. 

SECTION Pseudo-op 

Action: Program section 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: SECTION 

Assembler Syntax: 

SECTION <NAME>{,<TYPE>} 

Description: The SECTION directive is used to establish 
starting points for programs and subroutines. It is used to 
create relocatable program sections and operates in conjunc- 
tion with the linkage editor to create executable programs. 

The type field may be any one of the following 
keywords: 

CODE (default) Continue with the code section 
DATA Continue with the data section 

BSS Continue with the BSS section 
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SPC Pseudo-op [J 

Action: Space blank lines 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: SPC U 

Assembler Syntax: 

SPC <VALUE> 

Description: This pseudo-op generates the specified number [ 

of blank lines in the assembly listing file. This pseudo-op does 
not appear in the listing file. 

TEXT/CODE/DATA/BSS Pseudo-op 

Action: Text/Code/Data/BSS program section 
Condition Codes: X: - N: - Z: - V: - C: - 
Opcode Forms: TEXT/CODE/DATA/BSS 
Assembler Syntax: 

TEXT 

CODE 

DATA 

BSS 

Description: These directives change the current section to 

become the code, data or BSS section. The text and the code 

section are considered equivalent. None of the directives 

takes an operand, and the section name is assumed to the 

current section name. These directives can be considered 

shorthands for the section directive. 



U 



TTL Pseudo-op 

Action: Set program title 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: TTL 

Assembler Syntax: 

TTL <STRING> 

Description: This pseudo-op sets the title to be used as part I i 

of the heading in each page of the listing file. This string "~— ' 

should not be more than 64 characters in length. This 

pseudo-op does not appear in the listing file. I I 

U 
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XREF Pseudo-op 

Action: Define an external label 

Condition Codes: X: - N: - Z: - V: - C: - 

Opcode Forms: XREF 

Assembler Syntax: 

XREF <LABEL>{,<LABEL>. . .} 

Description: This pseudo-op gives the assembler a list of la- 
bels that may not be defined in this assembler file. The 
ASM68010 lifts the restriction that these labels must not be 
defined in the current file. Instead this pseudo-op is kept for 
backward capability, and is used as a flag to the assembler 
that the label names listed as arguments may not exist in 
the current assembly. 
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Common Assembly-Time 
Errors for the Amiga 



In almost every program there are bugs. Legend has it that in 
one of the first computers, the first programming problem 
found was caused when a moth flew into the computer and 
not only killed itself, but caused the giant computer to gener- 
ate the wrong answer to the program it was running. Since 
that time, whenever there's been a programming mistake, that 
mistake is known as a bug. 

Bugs come in two forms. These are runtime errors and 
compile- or assembly-time errors. A runtime error occurs when 
a running program does not produce the expected results. An 
assembly-time error is produced any time a compiler or as- 
sembler sees illegal input. Here's a look at some of the possi- 
ble assembly-time errors that might be seen during the course 
of writing an assembly language program. 

The following assembler errors are some of the most com- 
mon detected by the ASM68010 assembler. Most (if not all) of 
these assembly-time errors are also detected in other Amiga 
68000 assemblers. The actual wording of the error message 
may be different. It may be necessary to consult your specific 
assembler reference manual for the exact wording of the error. 

• ERROR: Invalid opcode 

This error normally occurs when an opcode has been 
misspelled and the assembler cannot tell what the real 
opcode should be. For example: 

MUVE.L D0,D1 ;COPY DO TO Dl 

This type of error can be corrected by fixing a spelling 
mistake. 

• ERROR: Multiply defined symbol 

This error normally occurs when there have been two 



379 



Appendix B 



label definitions for exactly the same label. For example: 

COPYSTART: 

MOVE.L #10,DO ;LOAD THE COUNT 

; . . . SOME TIME LATER 

COPYSTART: 

This type of error can be corrected by changing one of 
the label names and all the label references to that name. 
• ERROR: Wrong number of operands 

This error normally occurs when an assembly statement 
has too many or too few operands. For example: 

COPY DO TO Dl WITH TOO FEW 
OPERANDS 

TEST THE RESULT OF Dl WITH TOO 
MANY OPERANDS 



MOVE.L DO 
TST.L D0,D1 



DS.W 

DC.B 

TST.L DO 



G 
U 
U 
U 

u 



This error can be corrected by editing the line so that 
the proper number of operands appear. An MC68000 micro- 
processor reference manual should provide a list of the legal 
operands for an instruction. 

• ERROR: Invalid operand 

This error normally occurs when a statement has the 
wrong operand for a given instruction. For example: 

EOR.L VAL,D0 ; EOR VAL TO DO 

This error can be corrected by editing the line so that 
the correct operands are used. 

• ERROR: Odd address 

This error is generated by the assembler when it tries to 
assemble an instruction opcode starting at an odd address. 
Remember, all instructions MUST start on an even address. 
For example: 

FORCE AN EVEN ADDRESS (THIS IS 

DISCUSSED LATER) 

FORCE AN ODD ADDRESS (THIS IS 

DISCUSSED LATER) 

THIS INSTRUCTION IS NOW ON AN 

ODD ADDRESS 

This error may be corrected by adding an EVENPC I j 

macro or similar even-alignment facility. This bug also may 
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be corrected by removing the code or data that misaligned 
the instructions. 

• ERROR: Include file not found 

This error is usually generated when the assembler can- 
not find an include file, or the include file is named incor- 
rectly. Example: 

INCLUDE "HEDDR" ; NOTE THAT INCLUDE NAME IS 
; MISSPELLED 

• ERROR: Macro undefined 

This error is usually generated when a macro call is 
using the wrong name or the macro was never defined. 

• ERROR: Nonrelocatable expression 

This error is usually generated when an absolute expres- 
sion is used where only a relative expression is allowed. Ex- 
amples include using absolute addresses in Bcc instructions, 
or performing an illegal arithmetic operation on a value. For 
example: 

BRA LABEL/2 ; LABEL/2 IS AN ABSOLUTE EXPRES- 

; SION. 

This error can be corrected by editing the line and re- 
placing the absolute expression with a relocatable expression. 

• ERROR: Offset too large 

This error is generated whenever the offset for a Bcc, 
DBcc, or BSR instruction is larger than the maximum amount 
allowed. The range is —128 to 127 for short offsets, and 
-32768 to 32767 for a long offset. For example: 

BRA.S FARAWAY ; POSSIBLY A BRA OR BRA.L WILL 
; WORK HERE. 

First try making the branch a long branch if it is a short 
branch. Otherwise, rewrite or shorten the file or subroutine. 
To get this message because the routine itself is too big, the 
subroutine must be at least 32,768 bytes long. This is far too 
big for a single subroutine. 

• ERROR: Unmatched ENDC pseudo-op or ERROR: No clos- 
ing ENDC pseudo-op 

This error is generated when the assembler cannot 
match all the IFxx pseudo-ops with the same number of 
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ENDC pseudo-ops. For example: 

IFEQ 1 

TST.L DO 

END ; THE END OF THE FILE. 



u 
u 



u 



! I 



An ENDC needs to be added someplace, or an IFxx must be 

removed. Match up all the l¥xx with ENDCs, and find out 

which IFrt is missing it's ENDC. [__J 

• ERROR: Undefined symbol(s), can't fully link load module 

This error message is printed by ASM68010 when the -a 
flag is selected and at least one symbol is not defined in the 
source. If the symbol should have been defined, define it. If 
the symbol was defined in a different object module, an 
ALINK/BLINK of the two object files will have to be 
performed. 

Other Errors 

Many other errors can be produced by ASM68010 and the 
other Amiga assemblers. Here's a list of many of the other er- 
rors from ASM68010. 

• ERROR: Invalid character 

The assembler found an unexpected character. Check for 
a mistyped line. 

• ERROR: Invalid constant 

The assembler parsed a constant value where there 
shouldn't have been one. Check for a missing operator (+, 
—,/,*, or other operator). 

• ERROR: Invalid term 

The assembler found an illegal part of an expression as 
either the left or right side of an operator. Check for a 
mistyped line. 

• ERROR: Invalid operator 

The assembler thinks it should see an operator (+, — , 
/, *, and so on) but, instead, found a character it couldn't un- 
derstand. Check for a mistyped line. 

• ERROR: Invalid symbol 

The assembler found a symbol, and at least one charac- 
ter in the symbol is not legal. Check for illegal characters 
(something other than alphanumeric characters) in the 
symbol. 
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• ERROR: Invalid pseudo-op; ignored 

This pseudo-op is not understood by this compiler. It 
has been parsed and ignored. No operation or code has been 
generated by this line. 

• ERROR: Illegal macro definition 

The macro definition line was probably typed incor- 
rectly. The macro name may also be illegal in some manner. 

• ERROR: Invalid assignment 

An EQU statement has been typed incorrectly, or it is 
missing arguments. 

• ERROR: User signaled error 

The FAIL pseudo-op was executed by the assembler. 

• ERROR: Unmatched ENDM pseudo-op 

This error is generated when the assembler cannot 
match the MACRO pseudo-ops with the same number of 
ENDM pseudo-ops. 

• ERROR: Illegal macro redefinition 

The user has defined two macros with the same name. 

• ERROR: Unmatched else pseudo-op 

This error is generated when the assembler cannot 
match or is not preceded by an IFxx pseudo-op. 

• ERROR: Too many nested include files 

The programmer has nested include files too deeply. On 
ASM68010, this depth is eight include files. 

• ERROR: Too many nested conditional levels 

The programmer has nested conditional levels too 
deeply. On ASM68010, this depth is 16 levels. 

• ERROR: Nested macro too deep 

The programmer has nested macros too deeply. The 
ASM68010 allows a maximum depth of 16 levels. 
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Guru Meditation Numbers 



A guru meditation number decoding table can help debug r -, 

Amiga-specific programming errors. A guru meditation num- | ( 

ber has 16 hexadecimal digits and looks like: 

81000009.00281002 

You can decode such a message this way: 

SSGESPER.00ADDRES 

SS two-digit subsystem code 

GE two-digit general error code 

SPER four-digit specific error code 

ADDRES six-digit task memory address 



Subsystems: 


Code 


Meaning 


00 


CPU Trap (see below) 


01 


Exec 


02 


Graphics 


03 


Layers 


04 


Intuition 


05 


Math 


06 


Clist 


07 


DOS 


08 


RAM 


09 


Icon 


0A 


Expansion 


10 


Audio 


11 


Console 


12 


Gameport 


13 


Keyboard 


14 


TrackDisk 


15 


Timer 


20 


CIA Chip 


21 


Disk 


22 


Miscellaneous 


30 


Bootstrap 


31 


Workbench 


32 


DiskCopy 
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Sometimes the first digit of the subsystem is an 8 (as in 
the example above). In that case, ignore the 8, and read the 
subsystem number as a 1 in our example. That means there 
was an Exec error. 



General Error Codes: 



Code 


Meaning 


01 


Not enough memory 


02 


MakeLibrary 


03 


OpenLibrary 


04 


OpenDevice 


05 


OpenResource 


06 


I/O Error 


07 


Signal Absent 


Specific Error Codes: 


Exec: 




Code 


Meaning 


0001 


Checksum: exception vector 


0002 


Checksum: ExecBase 


0003 


Checksum: Library 


0004 


No memory for library 


0005 


Memory List damaged 


0006 


No memory for interrupt server 


0007 


InitAPtr 


0008 


Damaged Semaphore 


0009 


Can't free already-free memory 


000A 


Bogus Exception 


Graphics: 


Code 


Meaning 


0001 


No memory for Copper display list 


0002 


No memory for Copper instruction list 


0003 


Overloaded Copper list 


0004 


Overloaded Copper intermediate list 


0005 


No memory for Copper list head 


0006 


No memory (long frame) 


0007 


No memory (short frame) 


0008 


No memory for flood fill 


0009 


No memory for TmpRas in text operation 


000A 


No memory for BlitBitmap call 


O0OB 


Region Memory 


0030 


MakeVPort error 


1234 


GfxNoLCM 
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Layers: 

Code Meaning 

0001 No memory 

Intuition: [ J 

Code Meaning 

0001 Unknown gadget type c~, 

0002 No memory for port } | 

0003 No memory to allocate item plane 

0004 No memory for sub allocation 

0005 No memory for plane allocation 

0006 Item's top less than RelZero 

0007 No memory to open screen 

0008 No memory to allocate screen raster 

0009 Unknown screen type to open 
000A No memory to add SW gadgets 
000B No memory to open window 
000C Bad state return entering Intuition 
000D Bad message received by IDCMP 
000E Weird echo causing incomprehension 
000F Can't open console device 

DOS: 

Code Meaning 

0001 No memory at startup 

0002 EndTask didn't end task 

0003 Qpkt quick I/O failure 

0004 Unexpected packet received 

0005 Freevec failure 

0006 Disk block sequence error 

0007 Bitmap damaged 

0008 Key already free 

0009 Checksum error 
000A Disk error 
000B Key out of range 
000C Bad Overlay (may be linker-related) 

RAM 

Code Meaning 

0001 Bad segment list 

Expansion: 

Code Meaning 

0001 Bad expansion free 
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TrackDisk: 
Code Meaning 

0001 Calibration timing seek error 

0002 Timer wait error 

Timer: 

Code Meaning 

0001 Bad request 

0002 Bad supply 

Disk: 

Code Meaning 

0001 Unit already has disk 

0002 Interrupt; no active unit 

Bootstrap 
Code Meaning 

0001 System boot code returned error 

CPU Traps are internal microprocessor errors: 

Code Meaning 

00000002 Bus error 

00000003 Address error 

00000004 Illegal instruction 

00000005 Divide by zero 

00000006 CHK instruction 

00000007 TRAPV (Trap Vector) instruction 

00000008 Supervisor mode privilege violation 

00000009 Trace 

0OOOOOOA Line A trap (OpCode 1010) 

0000000B Line B trap (OpCode 1011) 

The CPU trap errors can often be traced back to program- 
ming errors like misused instruction sizes. Arranging the pro- 
gram so that words or long words fall on odd memory addresses 
frequently results in 00000003 or 00000004 errors. 

The actual subsystem general and specific errors above 
are usually traceable to misuse of memory (for instance, trying 
to free memory that is already free) or the failure of a library 
function. If a library function call returns an error code and 
your program doesn't bother to respond to it, the program will 
usually crash and present you with a guru message. For ex- 
ample, if Open Window fails and a program tries later to attach 
a menu to the nonexistent window, you'll run into problems. 
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If you try to allocate memory and fail, and then try to use the 
nonexistent memory, be prepared to visit the Guru. Memory 
that is not currently allocated, also cannot be freed. 

The process of debugging is an art, and a complete dis- I 

cussion of machine language debugging would be larger than ' — ' 

this book. The macros and subroutines in our support code 
files include error checking for library calls. Be sure your own J I 

code does the same. The best debugging is bug prevention. ' — > 

The Amiga ROM Kernel Reference Manual: Exec has more infor- 
mation on Amiga debugging tools. 

The Guru meditation example 81000009:00ttxt;ra means 
Exec error (ignore the initial eight), General Error 00 (no gen- 
eral error) and SPecific ERror 0009 (tried to free memory al- 
ready free.). The xxxxxx will be the address of the instruction 
that caused the error. 
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APPENDIX D 

An Introduction to the 
ASM68010 Assembler 



Introduction. ASM68010 is an MC68010 assembler that's com- 
patible with the AmigaDOS MC68000 ASSEM program pro- 
vided by Metacomco, as well as the MC68010 assembly 
language specifications provided by Motorola. 

This appendix is a reference manual for the ASM68010 as- 
sembler. Any variations between this assembler and the 
Metacomco assembler are noted. For a more thorough discus- 
sion of the M68000 family of microprocessors, please see Sec- 
tion 1 of the text. 

How to read this manual. This manual uses the follow- 
ing conventions throughout: 

• Operand sizes are: A byte equals 8 bits, a word equals 16 
bits, and a long word equals 32 bits. In many respects, the 
MC68000 and MC68010 microprocessors are compatible in 
Amiga systems. If a specific feature pertains to only one of 
the microprocessors, the appropriate name (MC68000 or 
MC68010) is used. 

• Braces denote optional arguments. Anything inside the 
braces ({ }) is considered optional to the instruction. 

• Brackets ([ ]) denote a choice among options, one of which 
must be selected. 

i The statement 

"""' CLR{.[BWL] } DO 

has four valid meanings. These are: 

U ~ J CLR DO 

CLR.B DO 

I CLR.W DO 

1 — ' CLR.L DO 

The MC68000 and MC68010 microprocessors. The 

1 j M68000 family of microprocessors have 16 general-purpose 
registers. These registers are general in the sense that specific 
instructions are not wired to use specific registers (for shift 
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counts or temporary values, for example), and addressing 
modes are not wired to use specific registers for base and dis- 
placement arithmetic. The M68000 series provides eight D (or 
data) registers and eight A (or address) registers, as well as the 
program counter and, depending upon the processor type, one 
or more special system registers. 

The data registers are used in arithmetic calculations, and j j 

may be used as index values in the various indexed addressing 
modes. On the MC68000 and MC68010 microprocessors, 
these registers cannot be used for indirection. The register 
names are D0-D7. 

The address registers normally contain addresses or ad- 
dress constants and are used as pointers to data elements in 
memory. The register names are A0-A7. Register A7 normally 
goes by another name. It is the stack pointer (although stack 
operations are not restricted to this register, as they are in 
many other microprocessor architectures). 

Other specific registers include the program counter (or 
PC); the status register (SR); and the condition code register 
(CCR), the bottom half of the status register. On the MC68010 
processor, there are some additional registers accessible only 
in supervisor mode. These include the vector base register 
(VBR), the source function code register (SFC), and the des- 
tination function code register (DFC). 

In supervisor mode on both the MC68000 and MC68010 
microprocessors, the programmer can access a second user 
stack pointer. The name of this register is the user stack 
pointer (USP). 

The M68000 series of processors were designed to directly 
address four gigabytes of memory. The MC68000 and 
MC68010 microprocessors directly address 16 Megabytes of f j 

this address space. Later processors, such as the MC68020, '• — 

allow direct access to the entire address range. 

In the 65xic series of microprocessors, the least significant I 1 
byte comes first. In the MC68000, a long word is four bytes 
long. If it is contained in bytes 0-3, byte will be the most 
significant byte, and byte 3 will be the least significant byte. f j 

One memory access restriction exists on the MC68000 and 
MC68010 microprocessors: Long words must be aligned on 
even boundaries. There are various techniques to insure this f~~| 

condition, including certain pseudo-ops and a macro provided 
in this book. 
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Writing machine language source code. 

Format of a machine language statement. The following 
template defines the most common form of an assembly state- 
ment line: 
{label field} {opcode and associated operands} {comments} 

This template shows there are three parts to an assembly 
statement. These parts, all of which are optional, are: 

• A label 

• An MC68000 or MC68010 microprocessor opcode and its as- 
sociated operands 

• Trailing comments 

Blank lines are considered null (empty) comment lines. 
Because many of the assembler directives have a slightly dif- 
ferent format, their specific formats are each discussed individ- 
ually in the assembler directive definition section. 

Labels and label definitions. A label, sometimes called a 
symbol, consists of a string of alphanumeric characters that re- 
fer to an absolute constant (or address) or relative constant (or 
address). A label may consist of upper- or lowercase ASCII 
characters, as well as any decimal digit, the underscore charac- 
ter, or a period. The first character of the label may not be a 
number. 

The following are examples of legal and illegal labels: 

Legal Labels 

a 

Aa 

R2d2 

Symbol 

FooBar 

A_Very_Long_but.legal.NAME 

Illegal Labels Reason 

3.141PI Leading digit 

Bad?Label Illegal character (?) 

quote_notlegal' Illegal character (') 

ASM68010 does not impose a limit on the length of a la- 
bel; however, for backward compatibility with the Metacomco 
assembler, you should limit labels to a maximum of 30 charac- 
ters. Some labels are predefined by ASM68010. The following 
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table lists these predefined labels: 

n 



Label Definition 

Current location counter (this symbol is not defined 

by the Metacomco assembler) 
* Current location counter (approved Metacomco 

symbol) I — . 

narg Number of arguments sent to a macro invocation j J 

(this symbol is not defined by the Metacomco 

assembler) 
NARG Number of arguments sent to a macro invocation 

(approved Metacomco symbol) 
d0-d7, D0-D7, All register names are predefined by the assembler 
a0-a7, A0-A7, 
sp, SP, pc, PC, 
and so on 

Labels are used in two different locations. The first is the 
label definition, and the second is in a label reference. Label 
definitions take two forms. When the assembler sees an EQU, 
SET, or REG assembler directive, it will define an absolute 
symbol whose value contains the appropriate value as defined 
by the assembler directive, and the value provided in the ex- 
pression. When the assembler sees an address label definition, 
it defines a relative address label whose value contains the ad- 
dress of the current location counter. This label may be used 
to change the flow of execution or as part of some other as- 
sembly-time calculation. 

An address label definition has two formats. If the first 
character of the label starts in position one of the input line, 
the label name will terminate at the first blank character, at a 
colon, or at the end of the input line, whichever comes first. If 
the label doesn't start at position one of the input line, the la- 
bel must be terminated with a colon. Any other form will 
cause an assembly-time error. 

To maintain compatibility with the Metacomco assembler, 
opcodes should not be used as label definitions. Although this 
is legal in the ASM68010 assembler, it is very ill-advised. 
Unlike opcodes, register names, and assembler directives, all 
labels are case sensitive, which means the labels Assem, 
ASSEM, and AsSeM are all considered to be different by the 
assembler. If the programmer does not wish to have case sen- 
sitivity, the assembler option -c C cancels it. See the section of 
assembler options for more information. 
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i J Labels, as described in the previous paragraphs, may be 

externally defined or referenced. The assembler directives 

, , XDEF, XREF, as well as the ASM68010 specific directives 

J GLOBL and GLOBAL, signal the assembler that a label is ac- 
cessible outside the scope of the file. If these directives are not 

___ used, the labels must exist within the current assembly input 

[J Ale. 

Another type of label, a local label, has a much shorter life 
span. A local label takes the form of a sequence of numbers. 
Some examples are 3, 1, and 10. The lifetime of these labels 
lasts only between the definition of two nonlocal labels. The 
advantage of local labels is that they may be redefined and re- 
used after each normal label definition. The following example 
shows this: 



GOES TO LABEL BAR 

GOES TO NEXT STATEMENT 

LEGAL INSTRUCTION (GOES TO NEXT 
STATEMENT) 

GOES TO NEXT STATEMENT 

ILLEGAL (ASSEMBLY TIME ERROR) 
THIS LABEL '2' IS UNDEFINED NOW 



n 



START: 

BRA BAR 

FOO: 

BRA 1 
1: NOP 

BRA 2 

2: 

BAR: BRA 1 

1: 

BRA 2 

QUIT BRA START 

ASM68010 Instruction Mnemonics/Opcodes. The second 
field is the MC68000 or MC68010 microprocessor instruction 
mnemonic, usually known as an opcode, and its correspond- 
ing operands. 

The general format of instruction mnemonics is a set of 
three or more ASCII characters, possibly followed by a period 
and a size specifier. The following size specifiers are used in 
MC68000 and MC68010 assembly language: 

B Signifies to the assembler a byte-sized opcode. 

W Signifies to the assembler a word-sized opcode. 

L Signifies to the assembler a long-word-sized opcode. 

The ASM68010 and Metacomco assemblers will parse 
opcodes of both upper- and lowercase letters. Opcodes may 
not start in the first column of an assembly line. Placing an al- 
phanumeric character in the first column of a line is the signal 
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Symbol 




Addressing Mode 


Rn 




Register direct 


(An) 




Address register indirect 


(An)+ 




Address register indirect with postincrement 


-(An) 




Address register indirect with predecrement 


dl6(An) 




Address register indirect with displacement 


d8(An,Rn{.[wl] }) 


Address register indirect with index and 






displacement 


Value 




Absolute or direct 


dl6(PC) 




Program counter with displacement 


d8(PC,Rn{.[wl] } ) 


Program counter with index and displacement 


#immediateval 


Immediate data 






Inherent 



In this table, Dn means any legal data register. An means 
any legal address register. Rn means any legal data or address 
register. PC means program counter. The symbols d8 and dl6 
specify an 8- or 16-bit offset, respectively. The term 
immediateval specifies any expression that may be evaluated as 
8, 16, or 32 bits wide. 

Running ASM68010. The command line interface (CLI) 
syntax for executing ASM68010 is: ASM [options] SOURCE 
[options]. Here is a list of the legal options that are available 
with ASM68010: 
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to the assembler to process a label. Most likely, a syntax error j^_J 

will result from misplacing an opcode in a label's position. 

The opcodes and their various formats are discussed indi- 
vidually in Appendix A. j j 

Operands and Addressing modes. Operands are the fields in 
an assembler that specify the data that the MC68000 or 

MC68010 instruction is going to process. MC68000 and l ( 

MC68010 microprocessor instructions accept either 0, 1, or 2 
operands. 

Appendix A specifies the set of legal operands that may 
be used with each instruction. An operand is a data reference. 
Operands come in three classes: 

• Addressing modes 

• Expressions 

• Addressing modes, which contain an expression 

The following is a list of the legal addressing modes avail- 
able on the MC68000 and MC68010 microprocessors: 
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Option 

-O OBJECT-FILE 



n 



n 

! 1 



-L LISTING-FILE 
-V ERROR-FILE 
-H HEADER-FILE 

-I INCLUDE-LIST 



H 

n 



n 



Meaning 

Redirect the output of the object module to 
the named file. By default if the assembly file 
has a .s extension, it is converted to a .o ex- 
tension. If the assembly file has a .asm exten- 
sion, it is converted to .obj. If the assembly 
file has neither of these extensions, a .obj ex- 
tension is appended to the object file name. 
Generate a listing file. Place the listing output 
in the named file. Listing files are not created 
by default. 

Redirect the error output to the named file. By 
default this output will appear in the current 
CLI window. 

Process the named header file before process- 
ing the source file. This command line argu- 
ment is equivalent to adding an include 
assembler directive, with the named file as the 
argument, in the first line of the source file. 
This argument specifies the list of directories 
to search when looking for include files. In 
ASM68010, multiple -I flags may be given. The 
form for listing multiple directories in either 
assembler is: -I DIR1,DIR2,DIR3, or -I 
DIR1 + DIR2 + DIR3, or -I "DIR1 DIR2 
DIR3". 

This tells the assembler not to print the lead- 
ing copyright banner lines. It is helpful when 
ASM68010 is called from another program 
such as ASMINT. 

The -C keyword processes a sublist of com- 
mand line arguments. These subarguments 
are: 

S Produce a symbol table dump (Metacomco-only). 

D Do not dump local symbols to symbol table. 

C Ignore upper-/lowercase in labels. 

X Generate a cross-reference listing (Metacomco-only). 

Wnum Set aside workspace amount (Metacomco-only). 

The ASM68010 parses all command line arguments, but simply 
ignores the requests noted as Metacomco-only, above. 

-E EQUATE— FILE Generate an equate file based on the assem- 
bled list of absolute symbols in the symbol 
table. 
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-Q Quiet Mode 



-C [S D C X Wnum] 
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-A AUTO-LINK 



-R Force Relative 
Mode 



When possible (it is always possible if there 
are no external references), generate a com- 
pletely linked load module. The result, if it is 
fully linked (no errors), is directly executable 
from the CLI. This flag lets you skip the 
ALINK/BLINK phase and proceed directly to 
the execution step, speeding the 
assemble/test/edit/assemble phase of pro- 
gram development. Use this option only if 
your source file has all symbols defined (see 
text). It works well with the files and pro- 
grams in this book. (This option is in 
ASM68010 only). 

This is the opposite of -A. This occurs by de- 
fault, and the flag is provided simply for 
consistency. 
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Decimal Hex 




1 
2 
3 
4 
5 
6 
7 
8 
9 

10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 





1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

1A 

IB 

1C 

ID 

IE 

IF 

20 

21 

22 

23 

24 

25 



ASCII 

NUL 

SOH 

STX 

ETX 

EOT 

ENQ 

ACK 

BEL 

BS 

HT 

LF 

VT 

FF 

CR 

SO 

SI 

DLE 

DC1 

DC2 

DC3 

DC4 

NAK 

SYN 

ETB 

CAN 

EM 

SUB 

ESC 

FS 

GS 

RS 

US 

SP 

! 

# 
$ 



Note 

NULL 

CTRL-A 

CTRL-B 

CTRL-C 

CTRL-D 

CTRL-E 

CTRL-F 

CTRL-G 

CTRL-H 

CTRL-I 

CTRL-J 

CTRL-K 

CTRL-L 

CTRL-M 

CTRL-N 

CTRL-O 

CTRL-P 

CTRL-Q 

CTRL-R 

CTRL-S 

CTRL-T 

CTRL-U 

CTRL-V 

CTRL-W 

CTRL-X 

CTRL-Y 

CTRL-Z 

Escape 

Cursor right 

Cursor left 

Cursor up 

Cursor down 

Space 

Exclamation point 

Quotation mark 

Pound sign 

Dollar sign 

Percent sign 



Ring bell 
Backspace 
Horizontal tab 
Line feed 
Vertical tab 
Form feed 
Carriage return 
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38 


26 


& 


Ampersand 


u 


39 


27 




Apostrophe (close single 
quote) 


L..-.J 


40 


28 


( 


Open parenthesis 


1 I 

1 


41 


29 


) 


Close parenthesis 


1 1 


42 


2A 


* 


Asterisk (multiply sign) 




43 


2B 


+ 


Plus sign 


1 1 


44 


2C 


/ 


Comma 


U 


45 


2D 


- 


Hyphen (minus sign) 




46 


2E 




Period (decimal point) 




47 


2F 


/ 


Slash (divide sign) 




48-57 


30-39 


Digits 0-9 






58 


3A 


i 


Colon 




59 


3B 


/ 


Semicolon 




60 


3C 


< 


Less-than sign (left 
arrow) 




61 


3D 


= 


Equal sign 




62 


3E 


> 


Greater-than sign (right 
arrow) 




63 


3F 


? 


Question mark 




64 


40 


@ 


At sign 




65-90 


41-5A 


Uppercase alphabet A-Z 






91 


5B 


[ 


Left bracket 




92 


5C 


\ 


Backslash 




93 


5D 


] 


Right bracket 




94 


5E 




Caret (up arrow) 




95 


5F 





Underscore (underline) 




96 


60 


t 


Apostrophe (open single 
quote) 




97-122 


61-7A 


Lowercase alphabet a-z 






123 


7B 


{ 


Left brace 




124 


7C 


i 


Vertical stroke 




125 


7D 


} 


Right brace 


u 


126 


7E 




Tilde 


127 


7F 


DEL 


Delete 


u 

U 

u 
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GLOSSARY 

Terms Used in Amiga 

Machine Language 

Programming 



Given the complexity of machine language programming and 
the Amiga's capabilities, this book presents a large amount of 
information in a dense format. For some, it may seem that cer- 
tain concepts spring forth without much explanation. This 
glossary should help. 

A 

An abbreviation of the word address, as in address register AO. 

Accumulator 

An accumulator is a temporary location used by a computer 
for saving intermediate results to a computation. Accumulators 
are normally limited in number, but are much faster than the 
larger main memory. On an MC68000, the eight data registers 
and eight address registers can be considered accumulators. 

Address 

A number or symbol standing for a memory location. When a 
microprocessor performs an instruction, or loads or stores data, 
it must be told where in memory to find the instruction or 
data. The microprocessor uses numbers to distinguish the dif- 
r~""j ferent memory locations. Each memory location has a numeri- 
cal address. In programs, the numerical addresses can be given 
symbolic names whenever it is convenient. 

! 1 

I Addressing Mode 

When the MC68000 reads from or writes to a memory loca- 
r— I tion, it can use any 32-bit number as an address (the highest 
eight bits are ignored). The microprocessor can calculate the 
address by combining a variety of numbers. In some modes, it 
adds together two registers to form an address. In other 
modes, it adds a constant value to a register to form an ad- 
dress. In still other modes, the address of data is represented 
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by the number held in one of the address registers. The pre- 
cise method used to combine numbers and registers to form 
an address is called an addressing mode. Each instruction dic- 
tates an addressing mode used for that instruction. If the in- 
struction manipulates data in a register, the addressing mode 
is called Register Direct. If the same instruction manipulates 
data in memory by pointing to the data with an address regis- 
ter, the addressing mode is called Address Register Indirect. The 
MC68000 microprocessor has 11 different addressing modes. 

ASCII 

The American Standard Code for Information Interchange 
(ASCII) is a coded list of numbers corresponding to all the let- 
ters, numerals, punctuation marks, diacritical marks, and 
spaces, and certain commands like line feeds, carriage returns, 
and sounding the bell. There are 128 different ASCII codes, so 
each can be represented by a byte. The first 32 codes are vari- 
ous commands, while the other 96 are printable characters. 
For example, in ASCII code, the letter A is equal to 65, B is 66, 
and so on. A complete ASCII list is available in Appendix E. 

Assembler 

An assembler is a program that reads a file of source code 
statements and produces a machine language program. Ma- 
chine language bypasses interpretation and "speaks" to the 
microprocessor in its own language, thus operating faster than 
high-level languages like BASIC. 

Binary 

Binary is the base 2 system. This is a system in which num- 
bers are expressed as sequences of Is and Os. Any number can 
be so expressed. Just as neighboring digits of a decimal num- 
ber are related by a factor of ten, binary digits are related by a 
factor of two. The number 3 is represented as 11 in binary. 

Bit 

A bit is a formally defined unit of information that 
distinguishes between two distinct possibilities (such as 
whether a switch is on or off). A single bit is usually written 
as a or 1, depending on whether the bit is off or on, respec- 
tively. By combining bits in groups, larger numbers of distinct 
possibilities can be distinguished by each group. For example, 
two bits can distinguish four distinct possibilities. The result of 
two successive coin flips has four outcomes: heads-heads, 
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1 heads-tails, tails-heads, tails-tails. These would be represented 
in binary as 11, 10, 01, and 00, respectively. Each combination 

|—| of on and off bits can represent a unique binary number. 

> i Strings of bits (Is and 0s) can be used to represent any 
number. 
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Bitmap 

A bitmap is a region of memory that's treated by a program as 
a rectangular block of graphic information. Each bit in the 
memory region is translated to on or off states of a single dot 
or pixel in the graphic display. When a bitmap contains 8K, it 
represents 64,000 distinct individual dots. They might be ar- 
ranged as a 320 X 200 array of pixels, each one on or off. 
Within the bitmap region in memory, the first 40 bytes would 
be treated as a single line at the top of the rectangle. Each suc- 
ceeding 40-byte (320-bit) portion of the memory region would 
represent the next line of dots on the screen. With proper 
hardware and software programming, a single 8K block of 
memory can be manipulated as if it were really 320 separate 
40-byte lines of dots. 

Blitter 

The blitter in an Amiga is a specialized coprocessor chip that 
manipulates memory as a bitmap. The blitter is also a 
microprocessor that can read and write memory directly. It's 
usually used to move bitmaps, so a region inside one bitmap 
can be placed in another region. The blitter's special advan- 
tage is its speed. It is roughly four times faster than the 
MC68000 microprocessor, at moving bitmaps (twice as fast as 
the MC68010). The blitter can be told to treat any region of 
chip memory as a rectangular bitmap. It plays an essential role 
in all Amiga displays and animation graphics. 

Bus Contention 

Although the Amiga has many specialized microprocessors, 
such as the blitter, in addition to the MC68000 micropro- 
cessor, it has only one bus. All information for all the 
microprocessors must travel along this bus. Therefore, there 
are times when operations must slow down while the central 
processing unit waits for the bus to clear. This condition is 
called bus contention. 
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Clear 

When a bit is set equal to 0, it is said to be cleared, or reset. 

CLI 

The Amiga's CLI (Command Line Interface) is a program for 
interaction with the Amiga, using typed-in commands. 



U 
U 

u 



Bus Error 

A bus error occurs whenever the MC68000 cannot access 

something on its processor/memory bus. This usually occurs if i . 

a program tries to access a piece of nonexistent memory. | j 

Byte 

A byte is a group of eight bits. Taken together as a unit, the j 

group can distinguish 256 different combinations of Is and 0s. 
Programmers use bytes to represent numbers ranging from 
to 255 (256 possible choices). A byte may contain graphic 
data, part of a word or a long word, an ASCII character, or a 
single value within the range 0-255. 

C and C Compiler 

C is a compiled high-level programming language that closely 
resembles machine language in many ways. A C compiler is a 
program that translates the C language into machine language 
modules. Using a C compiler has the look and feel of a high- 
level computer language like Pascal or Modula-2, but the C 
programmer can do things usually reserved for machine lan- 
guage programming. 

Chip Memory 

The lower 512K of memory is accessible to both the MC68000 
microprocessor and a variety of specialized chips like the 
blitter chip. Since all these microprocessors (also called chips) 
must use the same bus for data transfer, their operations are 
slowed slightly as a result of bus contention. Therefore, using 
chip memory will cause the Amiga to run slightly slower than 
using expansion memory (also known as fast memory). Also 
see Fast Memory, Public Memory, and Bus Contention. 
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Condition Codes 

Condition codes are bits stored in the computer which reflect . 

the outcome of the last processed instruction. These bits are j | 

used by other instructions, such as branches, when deciding if 

the program should change it's course and start executing code ( , 

someplace else in memory. [ J 
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Condition Code Register 

The condition code register is the lower eight bits of the status 
register. 

Copper 

The copper is a general purpose coprocessor that resides in 
one of the Amiga's custom chips. The copper can control 
nearly the entire graphics system, freeing the MC68000 to exe- 
cute programs. Among other things, it can control register up- 
dates, reposition sprites, change the color palette, update the 
audio channels, and control the blitter. 

Coprocessor 

A coprocessor is a separate microprocesor that uses the same 
memory as the main microprocessor, but which is specialized 
to certain routine tasks. The Amiga uses at least three copro- 
cessors that perform display, sound, and input/output func- 
tions more efficiently than the MC68000 main microprocessor. 

CPU 

The term CPU stands for Central Processing Unit. The CPU 
performs the work laid out for the computer in the form of 
programs. 

Crash 

The condition in which the Amiga finds itself if your program 
isn't written properly. When a computer is unable to interpret 
instructions as a result of faulty programming, it will crash. 
When it crashes, it will probably present you with a Guru 
meditation, and it will usually require a warm boot before any 
further action can be taken. 

n d 

An abbreviation of the word data, as in data register DO. 

I | Data 

Numbers or symbols stored in memory. 



Decimal 

Decimal is the base 10 counting system. It is the most com- 
monly used base, perhaps because humans have ten fingers. 
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Direct Memory Access Device (DMA) 

A piece of hardware capable of directly modifying the comput- 
er's memory without using the microprocessor. Non-DMA de- 
vices use the microprocessor to transfer data between the 
device and memory. A DMA device moves the data on its 
own, freeing the microprocessor to do other useful work at the 
same time. A computer with DMA devices is usually a higher- 
performance computer because, in essence, it can do several 
things at the same time. This means that more work can be 
done in less time. The net result is that the computer with 
DMA devices performs better than one without them. 

Fast Memory 

On the Amiga, this is memory beyond the base of 512K. This 
memory is inaccessible to the specialized chips of the Amiga. 
This eliminates bus contention, resulting in faster operation 
when expansion memory is used. Also see Chip Memory, Pub- 
lic Memory, and Bus Contention. 

Field 

A field is a portion of a data structure. It may contain a byte, a 
word, or a long word of information used to specify a feature 
of the structure. 

File 

An Amiga file is simply a sequence of bytes. The sequence can 
be in memory or on disk. Any stream of bytes can be manipu- 
lated as a file. The AmigaDOS operating system provides all 
the usual tools for manipulating files, including open, close, 
read, and write routines. Bytes of data can be stored in a file 
and later retrieved. 

Function 

See Subroutine. 

Guru Meditation Number | | 

When the Amiga crashes, it provides a number that gives you 

a clue to the nature of the programming error that led to the , 

crash. This number is known as a Guru meditation number. The | | 

format and meaning of Guru meditation numbers can be 
found in Appendix C of this book. 
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Hexadecimal (also known as HEX) 

A base- 16 numbering system. This system uses decimal digits 
0-9 and the letters A-F (which stand for the values 10-15). 
Two hexadecimal digits make up one byte (each digit is four 
bits). The number Fl in hex is equal to 241 decimal and 
11110001 in binary. Hexadecimal is frequently used in ma- 
chine language programs. 

High-Level Language 

A high-level language is a language that is not directly in 
touch with the CPU; you don't have to know much about ma- 
chine-level operations to program in a high-level language. A 
single statement in a high-level language may take several as- 
sembly language instructions to accomplish the same task. 
High-level languages are friendlier to use than assembly or 
machine language, but execute more slowly and require more 
memory. 

Index Value 

An index value is an offset — a number added to the begining 
address of an array. If the third element of a byte array is to 
be accessed, the index value is 2. If the fifth element of a long- 
word array is to be accessed, then the index value is 16 ( ( 
5 — 1)*4 = 16). This simple equation can be thought of as 
(ELEMENT* — 1) * size of elements in bytes. 

Interrupt 

An Interrupt is a signal to a computer that some external de- 
vice (such as a floppy disk) has completed it's current task and 
is ready to talk to the MC68000. This may mean that the disk 
has data for the MC68000, or that it is ready to write more 
data, or that the keyboard has a new character for the 
MC68000 to process. Many types of external devices may in- 
terrupt the MC68000. 

Intuition 

An internal library of programs used to manipulate windows, 
mouse, menus, and so on in the familiar Amiga user interface. 

Library 

A library is a group of related routines organized as a family. 
The library may have a jump table, which is a list of addresses 
of routines in the library. Using the library's jump table is a 
convenient way of accessing the routines. 
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Linked List 

Sequences of data can be arranged in memory so that one 
block is connected to the next, even though they are widely 
scattered. Each data block contains a pointer to the next block. 
The linked list can be manipulated as a list of elements, even 
though they are not contiguous. 

Linker 

A program that merges or links the object code from one pro- 
gram with another. One program part may contain routines or 
symbol definitions required by the other. The linker's job is to 
extract whatever information is required from each part, to 
make one workable program. 

Loader 

A loader finds enough available memory for a program, and 
then puts it there and adjusts the relocatable addresses accord- 
ingly. It then runs (starts) the program. 

Long Word 

A long word is four bytes, or 32 bits. Long- word integers have 
a numerical range of over 4 billion. 

Machine Language (also called Assembly Language) 

Machine language is the lowest-level language. An assembler 
reads machine language statements and translates them into 
machine instructions. Assemblers are designed to perform one- 
to-one translations of assembly statements to machine 
instructions. 

Macro 

A macro is a user-defined instruction. Once defined, an assem- 
bler replaces any later occurrence of its name with a predefined i 
block of statements known as the macro body. Everything be- ^ 
tween the MACRO and ENDM pseudo-ops is the macro body. 
The macro body can contain opcodes, label definitions, and I 

even calls to other macros. ^—^ 



Octal 

Octal is a base-8 counting system used on some computer sys- 
tems. Octal is normally used when a computer's instruction 
word is broken up into many three-bit fields. 
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Operating System 

An operating system is a collection of routines that manage a 
computer. These routines perform some of the more mundane 
jobs, such as monitoring and collecting input data from exter- 
nal devices (such as keyboards). These routines also do other 
jobs, such as starting new programs and keeping track of all 
resources. The operating system of the Amiga decides which 
program can write to the disk and which program must wait. 
If two programs tried to write to the disk simultaneously, both 
data files would be corrupted. Instead, programs request that 
the operating system write for them, and the operating system 
actually does the writing to the disk in such a way that all 
data files are kept separate and uncorrupted. 

Opcode 

Short for operation code. An opcode is an instruction for the 
microprocessor to execute, but the opcode itself is usually de- 
scribed alone — without reference to its operands (see next 
entry). The MOVE instruction may have various numerical 
opcodes, depending on its addressing mode and the operands 
associated with it. Each numerical instruction is a unique 
opcode. 

Operand 

An instruction can usually manipulate or operate on one or 
two pieces of data. These pieces of data are the instruction's 
operands. Addition requires two operands. Clearing a register 
requires one operand. Operands may be written as numbers or 
symbols. They may be registers or memory locations. 

Pointer 

A pointer is simply an address. Registers inside the micro- 
processor can hold addresses and may be called pointer regis- 
ters. Programmers can arrange that certain memory locations 
contain pointers to other data. Using MC68000 addressing 
modes, the pointers can be combined to form additional 
pointers. 

Program Counter 

The program counter is a special register that contains the ad- 
dress of the next instruction. The program counter increases as 
successive instructions are executed. When a branch or a jump 
occurs in a program, the program counter is adjusted to the 
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address to which the branch or jump occurred. The program 
counter in a MC68000 microprocessor can be used with ad- 
dressing modes to calculate addresses of other instructions and 
data in memory. 

PC 

See Program counter. 

Pseudo-Op 

A pseudo-op is a special assembler directive that is not trans- 
lated into machine language. Although it looks like an opcode 
(hence the name), it's really a special form of input to the as- 
sembler, telling it to set aside a number of bytes, generate a 
listing, or some other form of instruction. 

Public Memory 

When your program requests public memory from the operat- 
ing system, the operating system will provide either fast or 
chip memory. Fast memory will be provided if available, if 
not, your program will be given chip memory. All memory 
that is unallocated is public memory. At some point in the fu- 
ture, Commodore may release an Amiga operating system that 
provides for private memory, which will allow blocks of mem- 
ory to be designated for a single use. This is not currently 
available, however. Also see Chip Memory and Fast Memory. 

Register 

A register is an internal memory location within the micro- 
processor. The MC68000 has 16 general-purpose 32-bit regis- 
ters — eight data and eight address registers. Each address 
register can point to a different location in memory. Instruc- 
tions can directly manipulate data in a register or use the reg- I I 
ister to form the address of data in memory. The results of '-— J 
performing instructions are also kept in a 16-bit status register, 
while the program counter has its own 32-bit register. Regis- 
ters are usually limited in number but much faster than main 
memory. 
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Relocatable Code 

Programs can be written so that they must be executed start- 
ing at a particular address. Such programs are called fixed loca- j ■ 
Hon code. They must be stored in memory at a particular LJ 
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address in order to work. Relocatable code can work regard- 
less of where the program resides. Relocatable code usually re- 
quires the program counter to act as a relative reference point. 
The starting address of the program (initial program counter 
value when the program starts) is used to adjust any necessary 
addresses in the rest of the program before it runs. 

Reset 

This term has two meanings. When a bit is returned to a 
value, it's said to be reset. The second meaning of reset is to 
reboot the computer after a crash by pressing Control- Amiga- 
Amiga. 

Set 

When a bit is given a value of 1, it is said to be set. When it's 
set equal to 0, it is reset, or cleared. 

Sign Bit 

A designated bit of a byte, word, or long word can be inter- 
preted as a + or — sign. Usually a value there means 
+ , and a value of 1 means — . While a byte can represent 
values from to 255, if its leftmost bit is used as a sign, it rep- 
resents values from -128 (10000000) to +127 (01111111). 

Stack 

Almost all microprocessors have the ability to manipulate one 
portion of memory as if it were a list, one end for which data 
can be added to, or removed from. The stack is used to pass 
parameters to and from procedures, and to hold return ad- 
dresses. When data is added to the stack, the address of the 
stack's next available storage position is automatically adjusted 
by the microprocessor. Similarly, when data is removed from 
the stack, the next available address is moved back. Stacks 
may grow either up (increasing memory addresses) or down 
(decreasing memory addresses). The microprocessor's pointer 
to the next available stack position is called the stack pointer. 
The stack pointer is automatically adjusted up or down, de- 
pending on whether data is added or removed. 

Stack Pointer 

This register points to the top of the program's stack. 
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Structure 

A structure is a table of data consisting of bytes, words, and 
long words. Each element of a structure is usually given a field 
name. Each time a particular structure is used, its data appears 
in a unique ordering of bytes, words, and long words specific 
to that structure's definition. 

Subroutine 

A subroutine is a set of computer instructions outside of the 
main' portion of the program. It is good programming practice 
to organize a program into functional units. Each unit usually 
does one thing, and is called, when necessary, from other sub- 
routines. Subroutines are sometimes called functions. 

Warm Boot 

See Reset. 

Word 

A word is two bytes or 16 bits. Using a word, it's possible to 
distinguish 65536 different combinations of Is and Os. Pro- 
grammers use words to represent numbers between and 
65535 or, using the leftmost bit as a sign bit (see Sign Bit), be- 
tween -32768 and +32767. 

Workbench 

Workbench is the standard Intuition screen. It is a high- 
resolution (640 X 200) two-bitplane (four color) screen. Any 
application program can use the Workbench screen for open- 
ing its windows. 
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String | I 

A string is a sequence of ASCII characters or bytes of data that ' — ' 
represent a sequence of ASCII characters. Most strings are 

null-terminated, which means a byte is appended at the end j I 

of the string. ' — -" 
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absolute addressing mode 46, 53 

access modes 159 

ADD instruction 18, 26-28 

ADDQ (ADD Quick) instruction 27-28 

addressing modes, differences between 

MC68000 and MC68010 55-56 
addressing modes, MC68000 45-57 
address register indirect addressing 

mode 45, 46, 47-48 
address register indirect with displace- 
ment addressing mode 46, 50-51, 

160 
address register indirect with index and 

displacement addressing mode 46, 

51-53 
address register indirect with 

postincrement addressing mode 46, 

48-49 
address register indirect with 

predecrement addressing mode 46, 

49-50 
address registers (A registers) 4, 5-6 
ALINK command 72 
ALLOCREMEMBER library function 

128-31 
Amiga 500 computer vii 
Amiga 1000 computer vii 
Amiga 2000 computer vii 
AmigaDOS 153-64 
function table 154 
manual xiv 
Amiga VI. 2 Enhancer software xv 
AND instruction 30-32 
Apple Macintosh computer vii 
architecture, MC68000 microprocessor 

3-12 
ASCII 281 

code list 397-98 
ASL (Arithmetic Shift Left) instruction 

32,33 
ASM68010 assembler xv, xvi, 14, 71, 

389-96 
ASMINT.ASM program 295-307 
ASR (Arithmetic Shift Right) instruction 

32,33 
assembler directive 13, 78-82 
assemblers, available for Amiga viii, 

xv-xvi 
assembling source files 71 
ASSEM command 72-73 
ASSIGN command, CLI 67-68 
Atari ST series computers vii 
AUTOREQ.ASM program 253-54 
AUTOREQUEST Intuition call 247, 

249-50 



barrel shifter 57 

BASIC programming language vii, viii 

BCC (Branch Carry Clear) instruction 
38 

BCS (Branch Carry Set) instruction 38 

BEQ (Branch EQual) instruction 38 

BGE (Branch Greater or Equal) instruc- 
tion 38 

BGT (Branch Greater Than) instruction 
38 

BHI (Branch High) instruction 38 

BHS (Branch High or Same) instruction 
38 

bit manipulation 36-37 

BLE (Branch Less or Equal) instruction 
38 

BLO (Branch LOw or same) instruction 
38 

BLT (Branch Less Than) instruction 38 

BMI (Branch Minus) instruction 38 

BNE (Branch Not Equal) instruction 38 

book, prerequisites for using xiv-xvii 

books, useful xvi-xvii 

Boolean gadget 223, 230-31 

BOOLGADGET1.ASM program 231-32 

BOOLGADGET2.ASM program 233-35 

BPL (Branch PLus) instruction 38 

BRA (BRanch Always) instruction 38 

branch and loop instructions 37-40 

BSET (Bit SET instruction) 26 

BSR (Branch to SubRoutine) instruction 
42 

BTST (Bit TeST) instruction 36 

button 296-97 

BVC (Branch oVerflow Clear) instruc- 
tion 38 

BVS (Branch oVerflow Set) instruction 
38 

CD command, CLI 69 

chip memory 131 

CLI xiv, 61-69, 153 
starting programs from 154-55 
window, accessing 62 

CLIFLOAT program 283 

CLOSELIBRARY library function 117, 
120-21, 122-23 

CLOSESCREEN library function 272 

CLOSEWINDOW gadget 175 

CMP (CoMPare) instruction 39-40 

command keys, menus and 216 

command line interface. See CLI 

command line, reading 156 

commands, CLI 63-69 

comment field 19 

compiler fill 
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CON: AmigaDOS device 160-61 

conditional assembly 94-99 
within macros 95-96 

condition code register (CCR) 7 

condition codes, types of 37 

console window 160-63 

COPY command, CLI 63-64 

C programming language vii, viii, x-xi, 
136, 281 

custom screen, closing 272-73 

custom screen specification chart 268 

data registers (D registers) 4, 5 

data table 136-41 

DBCC (Decrement and Branch Carry 
Clear) instruction 40 

DBCS (Decrement and Branch Carry 
Set) instruction 40 

DBEQ (Decrement and Branch EQual) 
instruction 40 

DBF (Decrement and Branch False) in- 
struction 41 

DBGE (Decrement and Branch Greater 
or Equal) instruction 40 

DBGT (Decrement and Branch Greater 
Than) instruction 40 

DBHI (Decrement and Branch High) in- 
struction 40 

DBHS (Decrement and Branch High or 
Same) instruction 40 

DBLE (Decrement and Branch Less or 
Equal) instruction 40 

DBLO (Decrement and Branch LOw) 
instruction 40 

DBLS (Decrement and Branch Low or 
Same) instruction 40 

DBLT (Decrement and Branch Less 
Than) instruction 40 

DBMI (Decrement and Branch Minus) 
instruction 40 

DBNE (Decrement and Branch Not 
Equal) instruction 40 

DBPL (Decrement and Branch PLus) in- 
struction 40 

DBT (Decrement and Branch True) in- 
struction 41 

DBVC (Decrement and Branch 
oVerflow Clear) instruction 40 

DBVS (Decrement and Branch oVerflow 
Set) instruction 40 

DCx (Declare Constant) directive 79 

DELETE command, CLI 64 

destination function code register (dfc) 
9 

development files, organizing 100-112 

disk, companion to book xiv 

DIV instruction 28-30 
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DIVS (DIVide Signed) instruction 

29-30 
DIVU (DIVide Unsigned) instruction 

29-30 
DOSEQUATES.ASM program listing 

103-4 
DS.x (Declare Storage) directive 78-79 
Emacs text editor xiv, xv, 101, 167 
ENDC directive 94-95 
ENDCLI command, CLI 66-67 
END directive 80 
EOR instruction 30-32 
equate files 87-88, 102, 109-12 
EQU (EQUate) directive 79-80 
errors, common 379-83 
even-numbered addresses, importance 

of 12 
EXEC library 120-22, 127 
EXECUTE AmigaDOS function 163-64 
EXECUTE command, CLI 68 
fast floating-point number representa- 
tions 282 
fast memory 131-32 
FFP, ASCII conversion 282 
file 

handle 158 

locking 153 

types 158-59 
floating-point math 281-92 
floating-point number, definition of 281 
Fortran programming language vii, viii 
FPCMD.ASM program 288-90 
fractal line drawing 308 
freelist 128 
FREEREMEMBER library function 

128-31 
GADGETS.ASM program 227-30 
gadgets, Intuition 223-54 

flags 226-27 

programming hints 245-46 

types of 223 
GADGET structure 224-25 
GFX1.ASM program 261-62 
GFX2.ASM program 263-65 
GFXEQUATES.ASM program 257-58 
graphics 257-77 

library 257 

library function list 260 

3-D 322 
guru meditation numbers 384-88 
header file 87, 97-99 
heap 128 

high-byte/low-byte addressing 10 
HIWORLD.ASM program 73-77 
IDCMP 204 
IDCMPCLASS field 195 
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IDCMPCODE field 195 

IDCMPFLAGS field 192-93 

IF* directive 94-95 

immediate value addressing mode 46, 

55 
INCLUDE directive 86 

directive, conditional use of 97-98 
include files 83-89 

list of 85-86 
inherent addressing 47 
INPUT AmigaDOS call 154 
instruction formats, MC68000 13-19 
instructions, assembler. See opcodes 
instruction set, MC68000/MC68010 

337-38 
instructions, MC68000, most frequently 

used 20-44 
integer 281 

integer division operator (/) 81 
INTEGER gadget 224 
INTEQUATES.ASM program 167-72 
interlaced screen 308 
interpreter viii 

INTUIMESSAGE structure 195 
INTUITEXT structure 197-98 
Intuition 115-16, 167-91 

library functions list 173-74 

menus 204-22 

requesters 247-54 

screens 266-77 
JMP (JuMP) instruction 37 
JSR (Jump to SubRoutine) instruction 

42 
jump table 116 
kernel 83 

keyboard, reading 157 
label, format of 13-17 
LEA (Load Effective Address) instruc- 
tion 18, 24-26 
LENS. ASM program 317-22 
libraries, Amiga 115-27 
libraries, parameters and 120, 136 
libraries, ROM kernel 118 
libraries, STARTUP.ASM and 143 
library function, calling 124-27 
library macros 123-24 
library, opening, programming example 

118-20 
linking 72-73 
LIST command, CLI 66 
load module 72, 115 
local label 16-17 
logical instructions 30-32 
logical OR operator (!) 81 
long word 3 

LSL (Logical Shift Left) instruction 32, 
34 



LSR (Logical Shift Right) instruction 32, 

34 
machine language advantages of ix 
disadvantages of ix-x 
justification for vii-viii 
program, Amiga, development cycle 

of 70-77 
macros 90-94 
examples of 93-94 
nesting 92 

versus subroutines 92-93 
MACROS.ASM program listing 105-8 
MAKEAWINDOW subroutine 138-39 
MAKEDIR command, CLI 65-66 
Manx C compiler xv, xvi 
MATH.ASM program 283-87 
MathFFP library routines 291 
MathTrans library routines 292 
MC68010 microprocessor 3-4 
MC68020 microprocessor 3-4 
MC68030 microprocessor 3-4 
memory allocation 128-41 

program examples 132-35 
memory considerations, custom screens 

and 271-72 
memory layout, MC68000 9-12 
memory, types of 131-32 
menu 297-298 
menu structure, Intuition 217 
menu, removing 218-19 
MENU1.ASM program 211-14 
MENU2.ASM program 219-22 
MENUITEM flags 214-15 
MENUITEM structure 205 
MENUS. ASM program 206-11 
message, waiting for 194-96 
Metacomco assembler xiv, xv-xvi, 14, 

71, 84, 102 
Microemacs text editor. See Emacs 
microprocessors, other viii 
MOVE instruction 20-22 
MOVEM (MOVE Multiple registers) in- 
struction 22-24, 57 
MUL instruction 28-30 
MULS (MULtiply Signed) instruction 

28-29 
multitasking 115 
MULU (MULtiply Unsigned) instruction 

28-29 
NEG instruction 30-32 
NEWCLI command, CLI 66-67 
NEWSCREEN structure 266-70 
NEWWINDOW library function 

136-37, 138-39, 192-93 
NEWWINDOW structure 175, 176-80 
NOT instruction 30-32 
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object code 71 
opcode. See instruction 
opcode format 17-19 
opcodes, alphabetical listing of 338-62 
opcodes, two-operand 18-19 
OPEN AmigaDOS command 158 
opening files 158-60 
OPENLIBRARY library function 116, 

117, 122-23 
OPENSCREEN library function 266, 

273 
OPENWINDOW library function 

136-37, 175 
operand format 17-19 
operator directives 81-82 
OR instruction 30-32 
other programs, AmigaDOS and 

163-64 
OUTPUT AmigaDOS call 154 
POLYFRAC.ASM program 308-17 
program counter (PC) 7, 42 
program counter relative with displace- 
ment addressing mode 46, 54 
program counter relative with index 

and displacement addressing mode 

46, 54 
programming considerations, 16-bit 

56-57 
PROPGADGET1.ASM program 242-43 
PROPGADGET2.ASM program 243-45 
PROPINFO structure 240 
proportional gadget 224, 239-41 
protection, lack of in Amiga operating 

system 132 
pseudo-op. See assembler directive 
pseudo-ops, alphabetical listing of 

362-77 
public memory 132 
QUADRIX.ASM program 322-33 
RASTPORT structure 258-59 
READ AmigaDOS function 157 
register, 32-bit 3-4 
register direct addressing mode 45, 46, 

47 
registers, MC68000 family 4-9 
registers, special 7-9 
relocatable code 115 
RENAME command, CLI 64-65 
REQS.ASM program 250-52 



REQUESTER structure 248-49 

ROL (ROtate Left) instruction 32, 35 

ROR (ROtate Right) instruction 32, 36 

RTS (ReTurn from Subroutine) instruc- 
tion 42 

RUN command, CLI 68 

SCREEN.ASM program 273-77 

SCREEN structure 270-71 

shift and rotate instructions 32-36 

shift left operator («) 81-82 

sign extension 43-44 

size specifier 18 

source code, machine language and 
viii-x, 70-71 

source function code register (sfc) 9 

stack pointer (SP) 7 

STARTUP.ASM program 116, 129, 
142-49, 154-55 

status register (SR) 7, 8-9 

STRGADGET.ASM program 238-39 

string gadget 224, 235-37, 295-96 

STRINGINFO structure 236-37 

structures 136-41 

SUB instruction 26-28 

SUBQ (SUBtract Quick) instruction 
27-28 

subroutines 42-32 
structures and 138-39 

subtask 128 

supervisor mode 9 

SYSEQUATES.ASM program listing 
103 

TEXT.ASM program 198-200 

text handling, Intuition 196-98 

TST (TeST) instruction 40 

user mode 9 

user stack pointer (usp) 9 

vector base register (vbr) 9 

WAITPORT library function 194-96 

WINDOWPRINT program 201-3 

WINDOWS.ASM program 183-88 

windows, Intuition 174-75 

windows, refreshing 190-91 

WINDOW structure 188-90 

word 3 

work disk, organizing 100-102 

Workbench disk 61 

Workbench screen, limitations of 266 

WRITE AmigaDOS call 155 
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r-| To order your copy of the COMPUTB's Amiga Machine Lan- 
guage Programming Guide Disk, call our toll-free US order 
line: 1-800-346-6767 (in NY 212-887-8525) or send your pre- 
paid order to: 

COMPUTEI's Amiga Machine Language 

Programming Guide Disk 
COMPUTE! Publications 
F.D.R. Station 
P.O. Box 5038 
New York, NY 10150 

All orders must be prepaid (check, charge, or money order). NC 
residents add 5% sales tax. NY residents add 8.25% sales tax. 

Send copies of the COMPUTEi's Amiga Machine Language 

Programming Guide Disk at $1 9.95 per copy. (1 285BDSK) 

Subtotal $ 

Shipping and Handling: $2.00/disk $ 

Sales tax (if applicable) $ 

Total payment enclosed $ 

All payments must be in U.S. funds. 

_-. a Payment enclosed 

d Charge a Visa d MasterCard o American Express 

1—n Acct. No. Exp. Date 

i ( 

|— ) Name 



i 



(Required) 



Address 



City State Zip 

Please allow 4-5 weeks for delivery. 
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COMPUTE! Books 



Ask your retailer for these COMPUTEI Books or order directly from 
COMPUTE!. 

Call toll free (in US) 1-800-346-6767 (in NY 212-887-8525) or write COM- 
PUTEI Books, F.D.R. Station, P.O. Box 5038, New York, NY 10150. 



Quantity Title Price' Total 

COMPUTEI's Beginner's Guide to the Amiga 

(025-4) $16.95 

COMPUTEI's AmigaDOS Reference Guide 

(047-5) $16.95 

Elementary Amiga BASIC (041-6) $14.95 

COMPUTEI's Amiga Programmer's Guide (028-9) $17.95 

COMPUTEI's Kids and the Amiga (048-3) $14.95 

Inside Amiga Graphics (040-8) $17.95 

Advanced Amiga BASIC (045-9) $17.95 

COMPUTEI's Amiga Applications (053-X) $16.95 

Learning C: Programming Graphics on the $18.95 

Amiga and Atari ST 

COMPUTEI's First Book of Amiga (090-4) $16.95 



COMPUTEI's Amiga Machine Language 

Programming Guide (1 28-5) $19.95 

"Add $2.00 per book for shipping and handling. 
Outside US add $5.00 air mail or $2.00 surface mail. 

NC residents add 5% sales tax 

NY residents add 8.25% sales tax 

Shipping & handling: $2.00/book 

Total payment 



All orders must be prepaid (check, charge, or money order). 

All payments must be in US funds. 

D Payment enclosed. 

Charge □ Visa □ MasterCard □ American Express 

Acct. No Exp. Date- 
Name 



Address. 



City State Zip_ 

•Allow 4-5 weeks for delivery. 

Prices and availability subject to change. 

Current catalog available upon reauest. 
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COMPUTE! Books 



Ask your retailer for these COMPUTEI Books or order directly from 
COMPUTEI. 

Call toll free (in US) 800-346-6767 (in NY 212-887-8525) or write 
COMPUTE! Books, F.D.R. Station, P.O. Box 5038, New York, NY 10150. 



Quantity Title Price* Total 

Machine Language for Beginners (11-6) $16.95 

The Second Book of Machine Language (53-1) $16.95 

COMPUTED Guide to Adventure Games, Revised (67-1) $14.95 , 

Computing Together: A Parents & Teachers Guide 

to Computing with Young Children (51-5) $12.95 

COMPUTEI's Personal Telecomputing (47-7) $12.95 

BASIC Programs for Small Computers (38-8) $12.95 

Programmer's Reference Guide to the Color Computer (19-1) $12.95 

Home Energy Applications (10-8) $14.95 

The Home Computer Wars: An Insider's Account of 

Commodore and Jack Tramlel 

Hardback (75-2) $16.95 

Paperback (78-7) $ 9.95 

The Book of BASIC (61-2) $12.95 

The Greatest Games: The 93 Best Computer 

Games of All Time (95-7) $ 9.95 

Investment Management with Your Personal Computer (005) $14.95 

40 Great Flight Simulator Adventures (022) $10.95 

40 More Great Flight Simulator Adventures (043-2) $12.95 

100 Programs for Business and Professional Use 

(for IBM PC and Apple Computers) (01 7-3) $24.95 

From BASIC to C (026) $16.95 

The Turbo Pascal Handbook (037) $14.95 

Electronic Computer Projects (052-1) $10.95 

Flying on Instruments with Flight Simulator 

perfect bound (091-2) ' $ 9.95 

wire bound (103-X) $12.95 

Jet Fighter School 

perfect bound (092-0) $ 9.95 

wire bound (104-8) $12.95 

The Complete Desktop Publisher (065-3) $21.95 

I Didn't Know You Could do That with a Computerl (066-1) $14.95 

COMPUTEI's Flight Simulator Adventures for the Amiga, 

Atari ST, and Macintosh (100-5) $12.95 

Learning to Fly with Flight Simulator (11 5-3) $12.95 

• Add $2.00 per book for shipping and handling. Outside US add $5.00 air mail or $2.00 surface mail. 

NC residents add 5% sales tax. 

NY residents add 8.25% sales tax 

Shipping & handling: $2.00/book 

Total payment 

All orders must be prepaid (check, charge, or money order). 

All payments must be in US funds. 

□ Payment enclosed. 

Charge □ Visa □ MasterCard □ American Express 

Acct. No Exp. Date . 

Name 



(Required) 



Address 

City State Zip 

'Allow 4-5 weeks for delivery. Prices and availability subject to change. Current catalog available upon request. 
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Amiga Machine Language Programming 

COMPUTED Amiga UkscNn® languogis ProgrorwrilrQ 
GuitJfl is your gukJe to Amgp mqcrtne langiiage pi ogfam- 
mhg. It expahi the use of Indites, structures, and mo- 
china tanguoge cormqnds in creating useU useMriendy 
programs fhat cor'pha ql ihe escrlmg fearures of r^ 
Amiga's Intuition operating system. 

With such a capable system ot hardware end sort - 
ware, Ifs no wonde 1 programmers fina the Amga i*vthng 
For rhe programmer who wants ro learn he* la control the 
Amga eofrpJetery. machine language is fr* language of 
choice 

Here are just a few ttmgs yojl firva In tf*s book: 

- AmjgaDQS CLI and console use 

■ AmjgaDOS function -callng 

- htuticn windows: rnsnus: button,. s*nng. and sider pod- 
gets, and requeue*? 

► flocrthg-poinr mam 

- Example programs that demonstrate 3-D grochlcs; a var- 
oble moflfifvirtg whdow: ana fracfd Ina drawngs 

■ Methods rhot help yau o^ganee your wortdnfl 
envkTanrrpsn* 

• T he 66000 instructions and addressing "nodes 
» Macros, subroutines, branches and loops, and many other 
pfogrammng techniques 

Machine language is me most efficient way to pro- 
gram the Amga, and OOtfPl/TF/'s Amiga Machine Lan- 
guage PfCQfamtrmg Gukte wll help yau understand the 
canpieniriei and ?vod 'he cofTiplcatcns at Amiga pro- 
gramming. This is me book you'll turn to agon and agon 
as you program your Amiga In mochne anguoge. 



The urograms in ihii boc* are avalable an a compan- 
ion del; See rne coupon in the back for details. 



Sfttnr rHfjLmnoto Aa\p, ta# 512L to disk driin. ind *_• 
"■bin ii imiilfc ai ih* rurhfurion dii, mnramrf *mt. 
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ISBN D-*745i-Hfl-5 
519 9 5 



